basalt-core 0.0.0-rc5 → 0.2.0

package/native/core/TextDirection.cpp

@@ -0,0 +1,242 @@
+#include "TextDirection.h"
+
+#include "TextAlignments.h"
+#include "WritingDirections.h"
+
+#include <cstdint>
+#include <string>
+
+namespace basalt {
+
+namespace {
+
+// One code point from UTF-8, advancing `index`. Returns 0 for a byte that
+// cannot start a sequence, which the caller treats as neutral -- a layout
+// decision rather than a validation.
+std::uint32_t nextCodePoint(std::string_view text, std::size_t &index) {
+  const auto byte = static_cast<unsigned char>(text[index]);
+  std::size_t length = 1;
+  std::uint32_t value = byte;
+
+  if (byte >= 0xF0) {
+    length = 4;
+    value = byte & 0x07U;
+  } else if (byte >= 0xE0) {
+    length = 3;
+    value = byte & 0x0FU;
+  } else if (byte >= 0xC0) {
+    length = 2;
+    value = byte & 0x1FU;
+  } else if (byte >= 0x80) {
+    // A continuation byte with no lead. Skip it.
+    index += 1;
+    return 0;
+  }
+
+  if (index + length > text.size()) {
+    index = text.size();
+    return 0;
+  }
+  for (std::size_t offset = 1; offset < length; ++offset) {
+    const auto continuation = static_cast<unsigned char>(text[index + offset]);
+    if ((continuation & 0xC0U) != 0x80U) {
+      index += offset;
+      return 0;
+    }
+    value = (value << 6) | (continuation & 0x3FU);
+  }
+  index += length;
+  return value;
+}
+
+// The characters inside the Arabic block that are *numbers* rather than
+// letters: Arabic-Indic digits are class AN and the extended ones are class EN,
+// and neither is strong. Reading the block as a whole is the obvious mistake
+// and it makes a string of Arabic-Indic digits followed by Latin text a
+// right-to-left paragraph, which Unicode says it is
+// not. Asked by both halves below, which is why it is its own function: the
+// first version excluded them from the strong test and forgot the neutral one,
+// so a digit stopped the search as though it were a Latin letter.
+bool isArabicNumber(std::uint32_t code) {
+  return (code >= 0x0660 && code <= 0x0669) || code == 0x066B || code == 0x066C ||
+      (code >= 0x06F0 && code <= 0x06F9);
+}
+
+// The blocks whose letters are class R or AL. Written as ranges because that is
+// how Unicode allocates them, and ordered so a reader can check them against
+// the standard's block list.
+bool isStrongRightToLeft(std::uint32_t code) {
+  // Hebrew, and the two marks that are class R in their own right.
+  if (code == 0x200F /* RLM */ || code == 0x061C /* ALM */) {
+    return true;
+  }
+  if (code >= 0x0590 && code <= 0x05FF) {
+    return true;
+  }
+  // Arabic, minus its numbers; see isArabicNumber.
+  if (code >= 0x0600 && code <= 0x06FF) {
+    return !isArabicNumber(code);
+  }
+  // Syriac, Arabic Supplement, Thaana, NKo, Samaritan, Mandaic, Syriac
+  // Supplement, Arabic Extended-B and -A, in one range: U+0700..U+08FF is
+  // right-to-left throughout.
+  if (code >= 0x0700 && code <= 0x08FF) {
+    return true;
+  }
+  // Hebrew and Arabic presentation forms.
+  if (code >= 0xFB1D && code <= 0xFDFF) {
+    return true;
+  }
+  if (code >= 0xFE70 && code <= 0xFEFF) {
+    return true;
+  }
+  // The historical right-to-left scripts: Cypriot through Arabic Extended-C.
+  if (code >= 0x10800 && code <= 0x10FFF) {
+    return true;
+  }
+  if (code >= 0x1E800 && code <= 0x1EFFF) {
+    return true;
+  }
+  return false;
+}
+
+// Everything that is not a letter of some script: skipped, because P2 asks for
+// the first *strong* character.
+//
+// Spelled as what to skip rather than as what counts, because what counts is
+// every letter of every left-to-right script and no list of those is short.
+// What is skipped is ASCII punctuation and digits, the Latin-1 punctuation
+// block, combining marks, general punctuation and the block of currency and
+// symbol characters after it -- which is what sits in front of a word in real
+// text.
+bool isNeutral(std::uint32_t code) {
+  if (code == 0) {
+    return true;
+  }
+  if (isArabicNumber(code)) {
+    return true;
+  }
+  if (code < 0x0041) {
+    // Controls, space, digits and the punctuation before 'A'.
+    return true;
+  }
+  if (code >= 0x005B && code <= 0x0060) {
+    return true;
+  }
+  if (code >= 0x007B && code <= 0x00BF) {
+    // ASCII punctuation past 'z', the C1 controls, and Latin-1's punctuation
+    // and symbols, which end before the first accented capital.
+    return true;
+  }
+  if (code == 0x00D7 || code == 0x00F7) {
+    // Multiplication and division signs, which sit among the Latin letters.
+    return true;
+  }
+  if (code >= 0x0300 && code <= 0x036F) {
+    // Combining marks. A letter carrying one is strong; the mark is not.
+    return true;
+  }
+  if (code >= 0x2000 && code <= 0x2BFF) {
+    // General punctuation through the symbol blocks. The two right-to-left
+    // marks in here are answered before this is asked.
+    return true;
+  }
+  if (code >= 0x1F000 && code <= 0x1FAFF) {
+    // Emoji and the symbol planes.
+    return true;
+  }
+  return false;
+}
+
+} // namespace
+
+bool textStartsRightToLeft(std::string_view utf8) {
+  std::size_t index = 0;
+  while (index < utf8.size()) {
+    const std::uint32_t code = nextCodePoint(utf8, index);
+    if (isStrongRightToLeft(code)) {
+      return true;
+    }
+    if (!isNeutral(code)) {
+      // The first strong left-to-right character, which ends the search: P2
+      // takes the first strong character of either kind.
+      return false;
+    }
+  }
+  return false;
+}
+
+bool paragraphIsRightToLeft(std::optional<facebook::react::WritingDirection> direction,
+                            std::string_view utf8) {
+  if (direction.has_value()) {
+    switch (*direction) {
+      case facebook::react::WritingDirection::LeftToRight:
+        return false;
+      case facebook::react::WritingDirection::RightToLeft:
+        return true;
+      case facebook::react::WritingDirection::Natural:
+        break;
+    }
+  }
+  return textStartsRightToLeft(utf8);
+}
+
+bool layoutIsRightToLeft(std::optional<facebook::react::LayoutDirection> layoutDirection) {
+  return layoutDirection.value_or(facebook::react::LayoutDirection::LeftToRight)
+      == facebook::react::LayoutDirection::RightToLeft;
+}
+
+TextDirections textDirections(std::optional<facebook::react::WritingDirection> direction,
+                              std::string_view utf8,
+                              bool layoutRightToLeft) {
+  // What `start` and `end` mean: the direction the app *asked* for when it
+  // asked, and the layout's otherwise.
+  //
+  // Upstream's `RCTResolveTextAlignment` reads only the layout direction, so a
+  // `<Text writingDirection="rtl" textAlign="end">` is flush right on iOS. It
+  // is flush left here, which is the measured behaviour this file's table was
+  // written for: `end` is the edge a line finishes at, and a paragraph that
+  // said which way it runs has said which edge that is. Nothing is lost -- a
+  // paragraph that says nothing still follows the layout, which is upstream's
+  // whole rule -- and backlog/text.md records the divergence.
+  bool relative = layoutRightToLeft;
+  if (direction.has_value() && *direction != facebook::react::WritingDirection::Natural) {
+    relative = *direction == facebook::react::WritingDirection::RightToLeft;
+  }
+  return TextDirections{
+      .paragraph = paragraphIsRightToLeft(direction, utf8),
+      .relative = relative,
+  };
+}
+
+TextDirections paragraphDirections(const facebook::react::AttributedString &attributedString) {
+  // The first fragment, the way every other paragraph-level question here is
+  // answered: React Native resolves these onto every fragment from the <Text>
+  // that owns them, and an empty paragraph has nothing to mirror anyway.
+  const auto &fragments = attributedString.getFragments();
+  const bool layoutRightToLeft =
+      !fragments.empty() && layoutIsRightToLeft(fragments.front().textAttributes.layoutDirection);
+  return textDirections(writingDirection(attributedString),
+                        paragraphText(attributedString),
+                        layoutRightToLeft);
+}
+
+const char *paragraphTextAlignmentName(
+    const facebook::react::AttributedString &attributedString) {
+  const auto &fragments = attributedString.getFragments();
+  const std::optional<facebook::react::TextAlignment> alignment = fragments.empty()
+      ? std::optional<facebook::react::TextAlignment>{}
+      : fragments.front().textAttributes.alignment;
+  return physicalTextAlignmentName(
+      physicalTextAlignment(alignment, paragraphDirections(attributedString)));
+}
+
+std::string paragraphText(const facebook::react::AttributedString &attributedString) {
+  std::string text;
+  for (const auto &fragment : attributedString.getFragments()) {
+    text += fragment.string;
+  }
+  return text;
+}
+
+} // namespace basalt

package/native/core/TextDirection.h

@@ -0,0 +1,88 @@
+// Which way a paragraph runs, when the app did not say.
+//
+// `writingDirection` is three values -- `ltr`, `rtl` and `natural` -- and
+// `natural`, which is also the default, means "ask the text". React Native says
+// which answer it means: `WritingDirection::Natural` is commented upstream as
+// "determines direction using the Unicode Bidi Algorithm rules P2 and P3". P2
+// is the direction of the first strong character, where strong means a letter of
+// a left-to-right script (L) or of a right-to-left one (R or AL) -- digits,
+// punctuation, spaces and symbols are not strong and are skipped -- and P3 is
+// that a paragraph with no strong character at all runs left to right.
+//
+// ## Why this is here rather than asked of each engine
+//
+// Only one of the three engines answers it. Pango resolves the paragraph
+// direction itself when `auto_dir` is on, and `pango_find_base_dir` is P2
+// exactly. Core Text resolves it inside a frame, which the AppKit layer does
+// not use -- it draws its own lines so that `numberOfLines` can be honoured --
+// and DirectWrite does not resolve it at all: `SetReadingDirection` is told, and
+// a paragraph of Hebrew with nothing set is laid out left to right.
+//
+// So two of three need this, and the alternative to one shared answer is one
+// real answer and two approximations that differ -- which is the argument
+// AppPaths.h makes about the resource path, for the same reason: a paragraph
+// that aligns differently on two desktops is worse than one that aligns by a
+// rule written down here.
+//
+// `test_text.cpp` in the GTK suite holds this against `pango_find_base_dir`
+// over a list of scripts, so "the rule below is P2" is measured rather than
+// claimed, and a disagreement is a failing test rather than a paragraph nobody
+// looks at twice.
+//
+// ## What it does not do
+//
+// Isolates. P2 skips the characters between an isolate initiator (U+2066..68)
+// and its matching PDI, so an isolated Hebrew word followed by Latin text is a left-to-right paragraph
+// by the standard and a right-to-left one by this. React Native has no way to
+// emit an isolate, an app would have to put one in a string literal, and
+// handling them means tracking a stack -- so this is the line, and it is drawn
+// here rather than discovered later.
+
+#pragma once
+
+#include "TextAlignments.h"
+
+#include <react/renderer/attributedstring/AttributedString.h>
+
+#include <optional>
+#include <string_view>
+
+namespace basalt {
+
+// Unicode P2 over UTF-8: the first strong character's direction, or false --
+// left to right -- when there is none. Invalid UTF-8 is skipped rather than
+// refused; this is a layout decision, not a validator.
+bool textStartsRightToLeft(std::string_view utf8);
+
+// The direction a paragraph is laid out in: what the app asked for, or what the
+// text says when it asked for `natural` or for nothing.
+//
+// This is the question every relative alignment needs answered, and the reason
+// `textAlign: 'end'` was wrong on all three hosts: `end` is the edge a line
+// finishes at, which is the left one here.
+bool paragraphIsRightToLeft(std::optional<facebook::react::WritingDirection> direction,
+                            std::string_view utf8);
+
+// What the app's layout does, from the field React Native fills for exactly
+// this: `TextAttributes::layoutDirection`, set in
+// `ParagraphShadowNode::getContent` from `YGNodeLayoutGetDirection`. Absent
+// means left to right, which is what upstream's own `.value_or` does -- a
+// paragraph that reached a host without one is not a paragraph to guess about.
+bool layoutIsRightToLeft(std::optional<facebook::react::LayoutDirection> layoutDirection);
+
+// Both directions at once, which is what every caller wants: see
+// `TextDirections` in core/TextAlignments.h for why there are two.
+TextDirections textDirections(std::optional<facebook::react::WritingDirection> direction,
+                              std::string_view utf8,
+                              bool layoutRightToLeft);
+
+// The same, for a whole paragraph: the direction prop and the text come out of
+// the attributed string, and the layout direction off its fragments.
+TextDirections paragraphDirections(const facebook::react::AttributedString &attributedString);
+
+// The paragraph's text, concatenated, which is what the rule above reads. The
+// fragments are the paragraph: React Native splits a `<Text>` into one per
+// distinct set of attributes, and P2 asks about the whole of it.
+std::string paragraphText(const facebook::react::AttributedString &attributedString);
+
+} // namespace basalt

package/native/core/TextHighlight.h

@@ -0,0 +1,30 @@
+// What a selection looks like.
+//
+// A colour, in one place, for the same reason `core/FocusRing.h` holds the
+// focus ring's: a highlight that is the GTK theme's blue on one desktop,
+// `NSColor.selectedTextBackgroundColor` on another and `COLOR_HIGHLIGHT` on a
+// third is a difference an app did not ask for and cannot control. React Native
+// has no prop for it either -- `selectionColor` belongs to `<TextInput>`, not
+// to a paragraph -- so there is nothing an app could use to put the three back
+// in step afterwards.
+//
+// The focus ring's blue, at the alpha a wash wants. The highlight is drawn
+// *under* the glyphs and nothing recolours them, so it has to leave text of any
+// colour legible through it; a solid accent with white text is the other
+// convention and needs a second decision about the text, which React Native
+// gave the paragraph and this platform does not get to overrule.
+//
+// Separate from core/TextSelection.h, which is the state machine, because each
+// host's *widget* layer paints this and has no React Native in it: the same
+// split core/TextVerticalAlign.h is on the other side of.
+
+#pragma once
+
+namespace basalt {
+
+constexpr float kTextSelectionRed = 0.259F;
+constexpr float kTextSelectionGreen = 0.522F;
+constexpr float kTextSelectionBlue = 0.957F;
+constexpr float kTextSelectionAlpha = 0.35F;
+
+} // namespace basalt

package/native/core/TextSelection.cpp

@@ -0,0 +1,97 @@
+#include "TextSelection.h"
+
+#include "PlatformServices.h"
+
+#include <algorithm>
+#include <utility>
+#include <cmath>
+
+namespace basalt {
+
+void TextSelection::press(facebook::react::Tag tag, int index, facebook::react::Point at) {
+  // A press always ends the previous selection, whether or not this one becomes
+  // a selection of its own: clicking somewhere is how a person dismisses a
+  // highlight, and that has to happen on the press rather than on the release
+  // or the old highlight survives the click that was meant to end it.
+  tag_ = tag;
+  anchor_ = index;
+  focus_ = index;
+  origin_ = at;
+  pressed_ = tag != 0;
+  claimed_ = false;
+}
+
+bool TextSelection::moveTo(int index, facebook::react::Point at) {
+  if (!pressed_) {
+    return false;
+  }
+
+  if (!claimed_) {
+    const double dx = static_cast<double>(at.x) - static_cast<double>(origin_.x);
+    const double dy = static_cast<double>(at.y) - static_cast<double>(origin_.y);
+    if (std::sqrt(dx * dx + dy * dy) < kTextSelectionThreshold) {
+      // Still a tap as far as anybody can tell.
+      return false;
+    }
+    claimed_ = true;
+    focus_ = index;
+    // True exactly once per gesture, which is what the caller uses to cancel
+    // the touch sequence it had been reporting.
+    return true;
+  }
+
+  focus_ = index;
+  return false;
+}
+
+void TextSelection::release() {
+  pressed_ = false;
+}
+
+void TextSelection::clear() {
+  tag_ = 0;
+  anchor_ = 0;
+  focus_ = 0;
+  pressed_ = false;
+  claimed_ = false;
+}
+
+TextSelectionRange TextSelection::range() const {
+  if (!claimed_) {
+    return {};
+  }
+  const int start = std::min(anchor_, focus_);
+  const int end = std::max(anchor_, focus_);
+  return TextSelectionRange{start, end - start};
+}
+
+// --- Copying it ---------------------------------------------------------------
+
+namespace {
+
+std::function<std::string()> &provider() {
+  static std::function<std::string()> value;
+  return value;
+}
+
+} // namespace
+
+void setSelectedTextProvider(std::function<std::string()> value) {
+  provider() = std::move(value);
+}
+
+std::string selectedText() {
+  const std::function<std::string()> &ask = provider();
+  return ask ? ask() : std::string{};
+}
+
+bool copySelectedText() {
+  const std::string text = selectedText();
+  if (text.empty()) {
+    return false;
+  }
+  setClipboardText(text);
+  return true;
+}
+
+} // namespace basalt

package/native/core/TextSelection.h

@@ -0,0 +1,161 @@
+// Selecting text with a pointer, which is a desktop expectation and was a
+// `<Text selectable>` that did nothing.
+//
+// `BaseParagraphProps::isSelectable` is the field, and both `selectable` and
+// `userSelect` arrive in it -- React Native's own `Text.js` maps the style onto
+// the prop. What a host does with it is three questions, and only the third is
+// shared: where a point lands in the text, what rectangles a range covers, and
+// *what a press and a drag mean*. The first two are each engine's own
+// (`pango_layout_xy_to_index`, `CTLineGetStringIndexForPosition`,
+// `IDWriteTextLayout::HitTestPoint`); the third is this file, because it is a
+// state machine with edges, and three hosts guessing at the edges separately is
+// how they would come to disagree about what a click does.
+//
+// ## The hard part is arbitration, not the selection
+//
+// A press inside selectable text cannot immediately become a selection, because
+// a press is also how a `<Pressable>` wrapping that text is pressed, and how a
+// `<ScrollView>` containing it is dragged. Claiming on the press would break
+// both: a tap on a selectable label inside a button would select a word and
+// never fire `onPress`.
+//
+// So a press only *remembers* where it landed. The gesture becomes a selection
+// when the pointer has moved far enough to say the person is sweeping rather
+// than tapping, and at that moment the host cancels the touch sequence it had
+// been reporting -- which is what the responder system does on a phone when a
+// scroll claims a touch, and reads the same way to React: a touchstart, some
+// moves, a cancel.
+//
+// A press that never moves is a tap, and a tap clears whatever was selected,
+// which is what every desktop does.
+//
+// ## Indices are the host's own unit
+//
+// Pango counts UTF-8 bytes, Core Text and DirectWrite count UTF-16 code units,
+// and nothing here needs them to agree: a paragraph's selection never leaves
+// the host. There is no `onSelectionChange` for a `<Text>` -- the only event
+// `ParagraphEventEmitter` has is `onTextLayout` -- so the indices are between a
+// hit test and a highlight, both of which are the same engine's. What crosses
+// to the clipboard is the substring, not an offset.
+//
+// So this file does no arithmetic on an index beyond comparing and ordering
+// them, and says so here rather than inviting somebody to add a conversion.
+
+// What a selection *looks* like is core/TextHighlight.h, which is a colour and
+// no React Native: each host's widget layer paints it, and that layer cannot
+// include this file. Not included from here, so the dependency stays where it
+// is used.
+
+#pragma once
+
+#include <react/renderer/graphics/Point.h>
+#include <react/renderer/core/ReactPrimitives.h>
+
+#include <functional>
+#include <string>
+
+namespace basalt {
+
+// How far a pointer has to move before a press becomes a selection rather than
+// a tap, in points.
+//
+// Two, which is the smallest number that is not a shaky hand: a mouse delivers
+// sub-pixel motion on a trackpad, and a threshold of zero would turn every
+// click on selectable text into a selection and cancel every tap. React
+// Native's own `Pressability` allows a touch to wander much further before it
+// stops being a press, which is the right number for a finger and the wrong one
+// for a cursor.
+inline constexpr double kTextSelectionThreshold = 2.0;
+
+// An ordered range, which is what a highlight and a copy both want. `length` is
+// zero when nothing is selected.
+struct TextSelectionRange {
+  int start{0};
+  int length{0};
+
+  bool empty() const {
+    return length <= 0;
+  }
+};
+
+// Where a selection started and where the pointer is now, for one paragraph.
+//
+// One per surface rather than one per paragraph: selecting inside a second
+// `<Text>` clears the first, which is what a desktop does and what a single
+// anchor enforces by construction.
+class TextSelection {
+ public:
+  // A press at `index` inside the selectable paragraph `tag`, at `at` in the
+  // surface's coordinates. Nothing is selected yet; see the header.
+  void press(facebook::react::Tag tag, int index, facebook::react::Point at);
+
+  // The pointer has moved to `index` at `at`. Answers true the once, when the
+  // move claims the gesture: the caller cancels the touch sequence it was
+  // reporting and stops reporting moves.
+  //
+  // False, and no selection, until the pointer has travelled
+  // `kTextSelectionThreshold` from the press. False forever if the press was
+  // not inside selectable text.
+  bool moveTo(int index, facebook::react::Point at);
+
+  // The pointer is up. The selection stays on screen; what it stops is the
+  // dragging.
+  void release();
+
+  // Nothing is selected. A tap, a press in a different paragraph, a mutation
+  // that replaced the text: all of them end here.
+  void clear();
+
+  // Whether a drag is currently selecting rather than touching. The caller
+  // reports no touch moves while this is true.
+  bool dragging() const {
+    return claimed_ && pressed_;
+  }
+
+  // Whether there is a selection to draw, which outlives the drag.
+  bool active() const {
+    return claimed_ && !range().empty();
+  }
+
+  facebook::react::Tag tag() const {
+    return claimed_ ? tag_ : 0;
+  }
+
+  // The selected range, ordered: a drag to the left of its anchor selects the
+  // same text as a drag to the right.
+  TextSelectionRange range() const;
+
+ private:
+  facebook::react::Tag tag_{0};
+  int anchor_{0};
+  int focus_{0};
+  facebook::react::Point origin_{};
+  bool pressed_{false};
+  bool claimed_{false};
+};
+
+// --- Copying it ---------------------------------------------------------------
+//
+// The two places a copy is asked for are both outside the pointer path: a
+// `Copy` role in a menu, which `performMenuRole` performs, and Ctrl or Cmd with
+// C, which arrives at a window's key controller. Neither can reach the object
+// holding the selection -- one is in the platform services and the other in the
+// host's own main -- so the host leaves a way to ask here, which is the
+// arrangement `setWindowBoundsListener` and `setEventListenerInstaller` use for
+// the same reason.
+//
+// Set by whatever owns the selection: GtkTouchDispatcher, the AppKit mounting
+// manager, the Win32 window. Null when no host has set one, which is every
+// build that is not a host -- the tests and the portability probe.
+void setSelectedTextProvider(std::function<std::string()> provider);
+
+// What is selected, or empty when nothing is. Safe to call with no provider.
+std::string selectedText();
+
+// Puts it on the clipboard and says whether there was anything to put. False is
+// the answer a `Copy` role wants when no paragraph has a selection: it means
+// "ask the focused widget instead", which is what the role meant before
+// paragraphs could be selected at all.
+bool copySelectedText();
+
+} // namespace basalt