basalt-core 0.0.0-rc5 → 0.1.0

package/native/core/TextAlignments.h

@@ -0,0 +1,240 @@
+// `textAlign`, resolved to an edge.
+//
+// React Native 0.87 added `start` and `end` beside `left` and `right`, and the
+// two kinds are not the same question. `left` is the left of the box. `end` is
+// the edge a line of text *finishes* at, which in a right-to-left paragraph is
+// the left one -- so a paragraph with `writingDirection: 'rtl'` and
+// `textAlign: 'end'` is flush left, and all three hosts had it flush right.
+//
+// `natural`, which is the default, is the other relative one: the edge a line
+// starts from.
+//
+// ## Why a table in core rather than three enum mappings
+//
+// Because it was three enum mappings, and the three disagreed. Measured on
+// 2026-10-10, over a paragraph of Hebrew in a 300pt box, before this existed:
+//
+//   | the app wrote           | GTK   | AppKit | Win32 |
+//   | rtl + end               | right | right  | left  |
+//   | rtl + left              | left  | right  | left  |
+//   | hebrew + natural        | right | left   | left  |
+//   | hebrew + left           | right | left   | left  |
+//
+// Four rows, no two hosts agreeing on all of them, and one correct cell between
+// them -- Win32's `end`, which is right because DirectWrite's alignments are
+// themselves relative. Each host had made a local decision about one enum
+// value, and the question is not local: it is "which edge, given a direction",
+// asked three times.
+//
+// So the question is answered here, and what is left per host is the spelling:
+// a `PangoAlignment`, a Core Text flush factor, a `DWRITE_TEXT_ALIGNMENT`.
+// `core/TextDirection.h` answers the direction half.
+
+#pragma once
+
+#include "TextVerticalAlign.h"
+
+#include <react/renderer/attributedstring/AttributedString.h>
+#include <react/renderer/attributedstring/TextAttributes.h>
+
+#include <optional>
+
+namespace basalt {
+
+// Where the text sits in the box, with nothing relative left in it.
+//
+// `Justified` is here because React Native's enum has it, and it is not an edge
+// at all: every host passes it straight to the engine, which stretches the
+// lines and then puts the last one against the start edge. Kept in the enum so
+// that a caller switching on this handles it rather than falling into a default
+// that silently means left.
+enum class PhysicalTextAlignment { Left, Center, Right, Justified };
+
+// The two directions a paragraph has, which are not the same question.
+//
+// `paragraph` is which way the text runs: the `writingDirection` prop, or
+// Unicode's P2 over the text when the app said `natural` or said nothing. It
+// decides where an unaligned paragraph sits, because `natural` means "the edge
+// this text starts from".
+//
+// `relative` is what the words `start` and `end` mean, and that is the *app's*
+// layout direction rather than the text's. A mirrored app lays every other
+// relative thing out that way -- Yoga resolves `paddingStart` and
+// `marginEnd` against `LayoutConstraints::layoutDirection` -- and a paragraph
+// whose `textAlign: 'start'` pointed the other way from its own
+// `paddingStart` would be the one thing in the window facing backwards.
+//
+// Upstream resolves it the same way and in one place:
+// `RCTResolveTextAlignment` in `RCTAttributedTextUtils.mm` takes
+// `(textAlignment, layoutDirection)` and answers `Start` with the layout's
+// left or right. The direction reaches here in
+// `TextAttributes::layoutDirection`, which `ParagraphShadowNode::getContent`
+// fills from `YGNodeLayoutGetDirection` -- so it is Yoga's answer for this
+// paragraph, not a global, and it is right for a subtree an app mirrored on
+// its own.
+//
+// Upstream's iOS half also mirrors `left` and `right` themselves when the
+// layout is right to left. This platform does not, and backlog/text.md records
+// that with the measurement: `left` is the left of the box here, on all three
+// hosts, which is the rule the rest of this file is written to.
+struct TextDirections {
+  bool paragraph = false;
+  bool relative = false;
+};
+
+// The edge for `alignment`, given what the text does and what the layout does.
+//
+// No alignment at all is `natural`, which is React Native's own default and the
+// reason this takes an optional: a paragraph that said nothing still has an
+// answer, and in a right-to-left one it is not the left edge.
+inline PhysicalTextAlignment physicalTextAlignment(
+    std::optional<facebook::react::TextAlignment> alignment,
+    TextDirections directions) {
+  const bool rightToLeft = directions.paragraph;
+  if (!alignment.has_value()) {
+    return rightToLeft ? PhysicalTextAlignment::Right : PhysicalTextAlignment::Left;
+  }
+
+  switch (*alignment) {
+    case facebook::react::TextAlignment::Left:
+      return PhysicalTextAlignment::Left;
+    case facebook::react::TextAlignment::Right:
+      return PhysicalTextAlignment::Right;
+    case facebook::react::TextAlignment::Center:
+      return PhysicalTextAlignment::Center;
+    case facebook::react::TextAlignment::Justified:
+      return PhysicalTextAlignment::Justified;
+#if BASALT_RN_MINOR >= 87
+    // The two that arrived in 0.87, and the whole reason this file exists.
+    // Against the layout rather than the text: see TextDirections above.
+    case facebook::react::TextAlignment::Start:
+      return directions.relative ? PhysicalTextAlignment::Right : PhysicalTextAlignment::Left;
+    case facebook::react::TextAlignment::End:
+      return directions.relative ? PhysicalTextAlignment::Left : PhysicalTextAlignment::Right;
+#endif
+    case facebook::react::TextAlignment::Natural:
+      break;
+  }
+  return rightToLeft ? PhysicalTextAlignment::Right : PhysicalTextAlignment::Left;
+}
+
+// The edge's name, for the tree dump the three hosts compare line by line.
+//
+// The resolved edge rather than the prop, which is the point: `textAlign: 'end'`
+// is the same word on every host and a different edge depending on the
+// paragraph's direction, so printing the prop would compare the question rather
+// than the answer. Nothing else in a dump shows it -- a right-aligned paragraph
+// has the same box and the same string as a left-aligned one.
+inline const char *physicalTextAlignmentName(PhysicalTextAlignment alignment) {
+  switch (alignment) {
+    case PhysicalTextAlignment::Center:
+      return "center";
+    case PhysicalTextAlignment::Right:
+      return "right";
+    case PhysicalTextAlignment::Justified:
+      return "justified";
+    case PhysicalTextAlignment::Left:
+      break;
+  }
+  return "left";
+}
+
+// The name for a paragraph, which is the question a mounting manager has: it
+// holds the attributed string and wants the line to print.
+const char *paragraphTextAlignmentName(const facebook::react::AttributedString &attributedString);
+
+// How far along the line's own free space the text sits: 0 for the left edge,
+// 0.5 for the middle, 1 for the right.
+//
+// Core Text's `CTLineGetPenOffsetForFlush` takes exactly this, and it is what
+// the AppKit layer draws with -- it lays out its own lines so that
+// `numberOfLines` can be honoured, which means the frame never applies the
+// alignment and the offset has to be computed. Justified text is flush with the
+// start edge, which is where its last line goes.
+inline double textFlushFactor(PhysicalTextAlignment alignment, bool rightToLeft) {
+  switch (alignment) {
+    case PhysicalTextAlignment::Center:
+      return 0.5;
+    case PhysicalTextAlignment::Right:
+      return 1.0;
+    case PhysicalTextAlignment::Justified:
+      return rightToLeft ? 1.0 : 0.0;
+    case PhysicalTextAlignment::Left:
+      break;
+  }
+  return 0.0;
+}
+
+// --- The other axis ----------------------------------------------------------
+//
+// `textAlignVertical` puts the paragraph somewhere in its own box: `top`,
+// `bottom`, `center` or `auto`. `verticalAlign` is the cross-platform spelling
+// of the same thing and needs nothing of its own here -- React Native's
+// `Text.js` and `TextInput.js` both rewrite it into `textAlignVertical` before
+// the props are sent, with `middle` becoming `center`. Measured on 2026-10-10;
+// the backlog said the cross-platform name was dropped before any platform saw
+// it, which was true of ReactCommon and not of the JavaScript above it.
+//
+// `auto` is the top, which is what every engine does with no instruction and
+// what React Native's own default produces.
+//
+// Only reachable when the box is taller than the text, which for a paragraph
+// means a `<Text>` with a height of its own: a paragraph that Yoga sized to its
+// own content has nothing to be aligned inside.
+
+// What the app asked for, for the tree dump: "auto", "top", "center",
+// "bottom", or nullptr when it said nothing.
+//
+// The prop rather than the offset it produces, which is the opposite of the
+// horizontal line above and for a reason: the edge a line sits against is the
+// same word on every host and a different edge depending on the direction, so
+// printing the prop there would compare the question. Here the prop *is* the
+// answer, and the offset depends on the box, which differs between hosts by a
+// line's worth of font metrics. What this line proves is the whole chain from
+// JavaScript -- `verticalAlign` is rewritten into `textAlignVertical` by React
+// Native's own `Text.js`, and nothing else here can show that it arrived.
+inline const char *textAlignVerticalName(
+    std::optional<facebook::react::TextAlignmentVertical> alignment) {
+  if (!alignment.has_value()) {
+    return nullptr;
+  }
+  switch (*alignment) {
+    case facebook::react::TextAlignmentVertical::Auto:
+      return "auto";
+    case facebook::react::TextAlignmentVertical::Top:
+      return "top";
+    case facebook::react::TextAlignmentVertical::Center:
+      return "center";
+    case facebook::react::TextAlignmentVertical::Bottom:
+      return "bottom";
+  }
+  return nullptr;
+}
+
+// How far down its box the paragraph sits: 0 for the top, 0.5 for the middle,
+// 1 for the bottom. The same shape as the horizontal flush factor above, and
+// for the same reason -- it is the one number each of the three hosts can use,
+// over a Pango translation, a Core Text origin and a DirectWrite draw origin.
+inline double textVerticalFlushFactor(
+    std::optional<facebook::react::TextAlignmentVertical> alignment) {
+  if (!alignment.has_value()) {
+    return 0.0;
+  }
+  switch (*alignment) {
+    case facebook::react::TextAlignmentVertical::Center:
+      return 0.5;
+    case facebook::react::TextAlignmentVertical::Bottom:
+      return 1.0;
+    case facebook::react::TextAlignmentVertical::Top:
+    case facebook::react::TextAlignmentVertical::Auto:
+      break;
+  }
+  return 0.0;
+}
+
+// The offset that factor produces, given a box and the text in it, is
+// `textVerticalOffset` in core/TextVerticalAlign.h -- a separate header because
+// each host's widget layer needs it and has no React Native in it. The box is
+// only known while drawing, so that is where it is asked.
+
+} // namespace basalt

package/native/core/TextChecking.h

@@ -0,0 +1,133 @@
+// `spellCheck` and `autoCorrect`, as three states rather than two.
+//
+// Both are `std::optional<bool>` in React Native's text-input traits, and the
+// third state is the one that matters: **unset is not false.** A field that says
+// nothing about spell checking wants whatever the platform does by default,
+// which on a Mac is to check and on Linux is whatever the input method was
+// configured to do. Resolving unset to `false` would turn every ordinary field
+// into one that had opted out, and the app never said so.
+//
+// So the hosts are given three states and leave the toolkit alone for the third.
+// That is the same shape the accessible flags use, for the same reason: React
+// Native's optionals carry "did not say", and a platform default is a real
+// answer rather than a missing one.
+//
+// ## What each toolkit can honour, which is not the same pair
+//
+//   - AppKit has both, on an NSTextView: `continuousSpellCheckingEnabled` and
+//     `automaticSpellingCorrectionEnabled`. A single-line NSTextField has
+//     neither of its own -- the field editor it borrows while focused is the
+//     NSTextView that does -- which is why the peer applies them again when a
+//     field takes focus.
+//   - GTK has spell checking as an input *hint*, `GTK_INPUT_HINT_SPELLCHECK`
+//     and its negative, which is a suggestion to the input method rather than
+//     an instruction to a checker. It has no hint for autocorrection at all:
+//     `WORD_COMPLETION` is completion, which is a different offer.
+//
+// backlog/platform-macos.md and backlog/text.md record the halves that are not
+// a call on each platform.
+
+#pragma once
+
+#include <react/renderer/components/iostextinput/primitives.h>
+
+#include <optional>
+
+namespace basalt {
+
+// What an app asked for, with "did not say" kept.
+enum class TextCheckingFlag {
+  Unset,
+  On,
+  Off,
+};
+
+inline TextCheckingFlag textCheckingFlag(std::optional<bool> asked) {
+  if (!asked.has_value()) {
+    return TextCheckingFlag::Unset;
+  }
+  return *asked ? TextCheckingFlag::On : TextCheckingFlag::Off;
+}
+
+// Its name, for a tree dump: nullptr when the app said nothing, so the line is
+// absent rather than claiming a default the app did not ask for.
+inline const char *textCheckingName(TextCheckingFlag flag) {
+  switch (flag) {
+    case TextCheckingFlag::On:
+      return "on";
+    case TextCheckingFlag::Off:
+      return "off";
+    case TextCheckingFlag::Unset:
+      return nullptr;
+  }
+  return nullptr;
+}
+
+// `autoCapitalize` and `keyboardType`, which are the other half of the same
+// entry and the other way round: GTK can express both and macOS neither.
+//
+// Both are plain enums rather than optionals, so there is no "did not say"
+// here: React Native's default for capitalisation **is** sentences, which is
+// what iOS does, and a host that treated the default as "no opinion" would be
+// quietly disagreeing with every other platform. So the hint is set either way
+// and the comment above each mapping says what it means.
+//
+// Nothing resolves them in core beyond naming them for the dump: a GTK input
+// purpose and a GTK input hint are GTK's vocabulary, and AppKit has no
+// vocabulary to translate into. What is shared is the word both dumps print.
+
+// `autoCapitalize`, as React Native spells it in JavaScript.
+inline const char *autoCapitalizeName(
+    facebook::react::AutocapitalizationType type) {
+  switch (type) {
+    case facebook::react::AutocapitalizationType::None:
+      return "none";
+    case facebook::react::AutocapitalizationType::Words:
+      return "words";
+    case facebook::react::AutocapitalizationType::Sentences:
+      return "sentences";
+    case facebook::react::AutocapitalizationType::Characters:
+      return "characters";
+  }
+  return "sentences";
+}
+
+// `keyboardType`, as React Native spells it. The iOS-only and Android-only
+// members are named as they are written in a stylesheet rather than collapsed,
+// because a dump that said "default" for four different asks would hide which
+// one an app made.
+inline const char *keyboardTypeName(facebook::react::KeyboardType type) {
+  switch (type) {
+    case facebook::react::KeyboardType::Default:
+      return "default";
+    case facebook::react::KeyboardType::EmailAddress:
+      return "email-address";
+    case facebook::react::KeyboardType::Numeric:
+      return "numeric";
+    case facebook::react::KeyboardType::PhonePad:
+      return "phone-pad";
+    case facebook::react::KeyboardType::NumberPad:
+      return "number-pad";
+    case facebook::react::KeyboardType::DecimalPad:
+      return "decimal-pad";
+    case facebook::react::KeyboardType::ASCIICapable:
+      return "ascii-capable";
+    case facebook::react::KeyboardType::NumbersAndPunctuation:
+      return "numbers-and-punctuation";
+    case facebook::react::KeyboardType::URL:
+      return "url";
+    case facebook::react::KeyboardType::NamePhonePad:
+      return "name-phone-pad";
+    case facebook::react::KeyboardType::Twitter:
+      return "twitter";
+    case facebook::react::KeyboardType::WebSearch:
+      return "web-search";
+    case facebook::react::KeyboardType::ASCIICapableNumberPad:
+      return "ascii-capable-number-pad";
+    case facebook::react::KeyboardType::VisiblePassword:
+      return "visible-password";
+  }
+  return "default";
+}
+
+} // namespace basalt

package/native/core/TextColors.h

@@ -0,0 +1,83 @@
+// A fragment's foreground and background, with `opacity` applied.
+//
+// Three rules that were spelled twice, once per host, and one of them was not
+// spelled at all:
+//
+//   - the default foreground is **opaque black**, which is React Native's and
+//     not the platform's. AppKit's `labelColor` is white in dark mode and would
+//     make default text invisible on a light background; matching React Native
+//     is what keeps the same app looking the same on all three desktops.
+//   - `opacity` multiplies the alpha of both colours. No host read it, so a
+//     `<Text style={{opacity: 0.5}}>` inside another `<Text>` was fully opaque.
+//   - a background with no colour is not transparent black, it is *nothing*:
+//     drawing it would paint a box behind text that asked for none.
+//
+// Copied from upstream's `RCTEffectiveForegroundColorFromTextAttributes` and its
+// background counterpart, including the detail that opacity applies to the
+// default black as well: an app that sets opacity and no colour still gets
+// translucent text.
+
+#pragma once
+
+#include <react/renderer/attributedstring/TextAttributes.h>
+#include <react/renderer/graphics/Color.h>
+
+#include <cmath>
+#include <optional>
+
+namespace basalt {
+
+// A straight sRGB colour, which is what both toolkits want handing over.
+struct TextColor {
+  float red{0.0F};
+  float green{0.0F};
+  float blue{0.0F};
+  float alpha{1.0F};
+};
+
+// `opacity`, as a factor. NaN is React Native's "unset" and means 1; a value
+// outside 0..1 is clamped, a stylesheet being able to ask for either.
+inline float textOpacity(const facebook::react::TextAttributes &textAttributes) {
+  if (std::isnan(textAttributes.opacity)) {
+    return 1.0F;
+  }
+  const float opacity = static_cast<float>(textAttributes.opacity);
+  if (opacity < 0.0F) {
+    return 0.0F;
+  }
+  return opacity > 1.0F ? 1.0F : opacity;
+}
+
+// The colour the glyphs are drawn in.
+inline TextColor textForegroundColor(
+    const facebook::react::TextAttributes &textAttributes) {
+  TextColor color;
+  if (textAttributes.foregroundColor) {
+    const auto components =
+        facebook::react::colorComponentsFromColor(textAttributes.foregroundColor);
+    color.red = components.red;
+    color.green = components.green;
+    color.blue = components.blue;
+    color.alpha = components.alpha;
+  }
+  color.alpha *= textOpacity(textAttributes);
+  return color;
+}
+
+// The colour behind them, or nothing.
+inline std::optional<TextColor> textBackgroundColor(
+    const facebook::react::TextAttributes &textAttributes) {
+  if (!textAttributes.backgroundColor) {
+    return std::nullopt;
+  }
+  const auto components =
+      facebook::react::colorComponentsFromColor(textAttributes.backgroundColor);
+  TextColor color;
+  color.red = components.red;
+  color.green = components.green;
+  color.blue = components.blue;
+  color.alpha = components.alpha * textOpacity(textAttributes);
+  return color;
+}
+
+} // namespace basalt

package/native/core/TextDecorations.h

@@ -0,0 +1,101 @@
+// `textDecorationLine`, `textDecorationColor` and `textDecorationStyle`.
+//
+// The line was read on both hosts and the other two were not, so an underline
+// was always a solid one in the text's own colour. What is shared here is the
+// resolution rather than the drawing: which lines are on, what colour they are
+// when an app names one, and the style it asked for. Each toolkit then maps the
+// style to its own vocabulary, and they do not have the same one.
+//
+// ## What each toolkit can draw, which is not the same list
+//
+// React Native has five styles -- solid, double, dotted, dashed and wavy -- and
+// neither desktop has all five:
+//
+//   - Core Text takes a style and a *pattern* in one bitmask, so
+//     `NSUnderlineStyleSingle | NSUnderlineStylePatternDot` is a dotted
+//     underline and `...PatternDash` a dashed one. It has no wavy.
+//   - Pango's underline is an enum with no patterns in it:
+//     `PANGO_UNDERLINE_SINGLE`, `DOUBLE` and `ERROR`, the last being the wavy
+//     red one a spell checker draws. So dotted and dashed have no value, and
+//     strikethrough is a boolean with no style at all.
+//
+// So each host draws what it has and falls back to a single line otherwise,
+// which backlog/text.md records with the call that would close the gap: drawing
+// the line in the snapshot rather than asking the text engine for it.
+//
+// Falling back rather than refusing is the choice worth stating. A dotted
+// underline drawn solid is wrong in a way a reader can see; a dotted underline
+// not drawn at all is wrong in a way that looks like the prop being ignored,
+// which is what the three props were doing before any of this.
+
+#pragma once
+
+#include <react/renderer/attributedstring/TextAttributes.h>
+#include <react/renderer/graphics/Color.h>
+
+#include <optional>
+
+namespace basalt {
+
+// One fragment's decoration, in the terms both hosts take.
+struct TextDecoration {
+  bool underline{false};
+  bool strikethrough{false};
+  facebook::react::TextDecorationStyle style{facebook::react::TextDecorationStyle::Solid};
+  // Unset means the text's own colour, which is what both toolkits do when no
+  // decoration colour is given, and is React Native's default: iOS sets
+  // `NSUnderlineColorAttributeName` only when `textDecorationColor` is there.
+  bool hasColor{false};
+  float red{0.0F};
+  float green{0.0F};
+  float blue{0.0F};
+  float alpha{0.0F};
+};
+
+// What a fragment decorates, or nothing.
+//
+// `textDecorationLine` is the prop that decides whether there is a decoration at
+// all: a colour or a style with no line is an app styling something it did not
+// ask for, and drawing a line there would be inventing one.
+inline std::optional<TextDecoration> textDecoration(
+    const facebook::react::TextAttributes &textAttributes) {
+  using facebook::react::TextDecorationLineType;
+
+  if (!textAttributes.textDecorationLineType.has_value()) {
+    return std::nullopt;
+  }
+
+  TextDecoration decoration;
+  switch (*textAttributes.textDecorationLineType) {
+    case TextDecorationLineType::None:
+      return std::nullopt;
+    case TextDecorationLineType::Underline:
+      decoration.underline = true;
+      break;
+    case TextDecorationLineType::Strikethrough:
+      decoration.strikethrough = true;
+      break;
+    case TextDecorationLineType::UnderlineStrikethrough:
+      decoration.underline = true;
+      decoration.strikethrough = true;
+      break;
+  }
+
+  if (textAttributes.textDecorationStyle.has_value()) {
+    decoration.style = *textAttributes.textDecorationStyle;
+  }
+
+  if (textAttributes.textDecorationColor) {
+    const auto components =
+        facebook::react::colorComponentsFromColor(textAttributes.textDecorationColor);
+    decoration.hasColor = true;
+    decoration.red = components.red;
+    decoration.green = components.green;
+    decoration.blue = components.blue;
+    decoration.alpha = components.alpha;
+  }
+
+  return decoration;
+}
+
+} // namespace basalt