basalt-appkit 0.0.0-rc5 → 0.2.0

package/native/appkit/RnTextLayout.h

@@ -10,6 +10,27 @@
 #ifdef __OBJC__
 #import <Cocoa/Cocoa.h>
 
+// Annotated as a whole, the way RnAppKitView.h is: one `nullable` in a file
+// turns on -Wnullability-completeness for every pointer in it, and the shadow
+// colour below is genuinely optional.
+NS_ASSUME_NONNULL_BEGIN
+
+// A wavy underline, which Core Text has no pattern for.
+//
+// `NSUnderlineStyle` is a bitmask of a line style and a *pattern* -- dot, dash,
+// dash-dot -- and there is no wavy member: the squiggle under a misspelling is
+// drawn by the text system's spell checking rather than by an underline. So
+// `textDecorationStyle: 'wavy'` came out as a straight line, which GTK draws
+// correctly and this host did not.
+//
+// The attribute is left off a wavy range and this key carries the colour the
+// line should be drawn in, which the layout strokes itself in
+// `drawInContext:size:`. An attributed string taking keys nobody else knows is
+// AppKit's own extension point, and it keeps the squiggle attached to exactly
+// the characters that asked for it -- a nested `<Text>` with a wavy underline
+// inside a plain one is two ranges and draws as two.
+extern NSAttributedStringKey const RnWavyUnderlineAttributeName;
+
 @interface RnTextLayout : NSObject
 
 @property(nonatomic, readonly) NSAttributedString *attributedString;
@@ -18,6 +39,37 @@
 @property(nonatomic, readonly) CTLineTruncationType truncationType;
 @property(nonatomic, readonly) BOOL truncates;
 
+// The paragraph's text shadow, from core/TextShadows.h: an offset in React
+// Native's coordinates -- y down -- the gaussian's standard deviation, and a
+// colour, or nil for no shadow.
+//
+// Core Text does not honour an `NSShadow` attribute the way AppKit's own text
+// drawing does, so this is set on the context around the line drawing rather
+// than carried in the attributed string. `standardDeviation` is what
+// `CGContextSetShadowWithColor` calls blur and is what React Native hands over,
+// which is why nothing here converts it.
+// Whether the paragraph runs right to left, resolved.
+//
+// The paragraph style carries `baseWritingDirection`, and its default --
+// `NSWritingDirectionNatural` -- means "ask the text", which only a frame
+// resolves. This layer draws its own lines so that `numberOfLines` can be
+// honoured, so no frame ever gets the chance: a paragraph of Hebrew with
+// nothing set drew flush left. The answer comes from core/TextDirection.h on
+// the React Native side, where the text is, and the default of NO is what a
+// paragraph built by hand means -- the style's own direction still stands.
+@property(nonatomic) BOOL rightToLeft;
+
+// How far down its own box the paragraph sits: 0 for the top, 0.5 for the
+// middle, 1 for the bottom, which is what `textAlignVertical` asks for and what
+// `verticalAlign` becomes in React Native's own JavaScript. The offset it
+// produces is core/TextVerticalAlign.h's, applied while drawing, because the
+// box is only known then.
+@property(nonatomic) CGFloat verticalFlush;
+
+@property(nonatomic, strong, nullable) NSColor *shadowColor;
+@property(nonatomic) CGSize shadowOffset;
+@property(nonatomic) CGFloat shadowStandardDeviation;
+
 + (instancetype)layoutWithAttributedString:(NSAttributedString *)attributedString
                       maximumNumberOfLines:(NSInteger)maximumNumberOfLines
                             truncationType:(CTLineTruncationType)truncationType
@@ -31,8 +83,62 @@
 // places the two platforms differ in shape rather than in spelling.
 - (CGSize)sizeForWidth:(CGFloat)maxWidth;
 
+// Where the character at `index` sits once the paragraph is broken at `maxWidth`,
+// in paragraph coordinates with y growing downwards, which is what the layer
+// above uses. `index` is a UTF-16 offset, the unit NSAttributedString counts in.
+//
+// For an inline view this is the box a run delegate reserved, so the origin is
+// its top-left corner. CGRectNull when the index is past the end, or past a
+// `numberOfLines` truncation, which is a real answer rather than a failure: the
+// view is not on screen.
+- (CGRect)frameForCharacterIndex:(NSUInteger)index width:(CGFloat)maxWidth;
+
+// --- Selecting that text ------------------------------------------------------
+//
+// The range to draw as selected, in UTF-16 code units -- what
+// `NSAttributedString` counts and what the hit test below answers. Length zero
+// selects nothing, which is how a selection is cleared.
+//
+// The state machine above this -- what a press and a drag mean -- is
+// core/TextSelection.h, shared with the other two hosts. What is here is the
+// part that needs Core Text.
+@property(nonatomic) NSRange selection;
+
+// The character index nearest a point in the view's own coordinates, inside a
+// box of `size` -- the same box `drawInContext:size:` is given, because the
+// answer depends on all of it: the width breaks the lines, and the height is
+// what `textAlignVertical` moved the paragraph inside.
+//
+// Nearest rather than inside: a point past the end of a line answers the end of
+// that line, and a point above the first or below the last answers that line,
+// which is what dragging off the edge of a paragraph has to mean.
+- (NSUInteger)characterIndexAtPoint:(CGPoint)point size:(CGSize)size;
+
+// The selected text, or nil when nothing is selected. What the clipboard takes:
+// a substring rather than a pair of offsets.
+- (nullable NSString *)selectedText;
+
+// The character range of each line this paragraph breaks into at `maxWidth`,
+// as NSValue-wrapped NSRanges, after `numberOfLines` and any truncation.
+//
+// For a screen reader, which reads a paragraph line by line and asks which
+// line an index is on. The lines are the visual ones -- a wrapped sentence is
+// several, which is what the person listening hears -- and they are Core
+// Text's own, so they match what is drawn rather than approximating it.
+- (NSArray<NSValue *> *)lineRangesForWidth:(CGFloat)maxWidth;
+
+// How far down a box `size` the paragraph is drawn: 0 unless `verticalFlush`
+// says otherwise, and the number the draw and the hit test both use.
+//
+// Public because an inline `<View>` has to move with the text it sits in: React
+// Native places an attachment from the top of the content box and knows nothing
+// about `textAlignVertical`.
+- (CGFloat)verticalOffsetForSize:(CGSize)size;
+
 // Draws into `context`, top-left origin, in a box `size` wide and tall.
 - (void)drawInContext:(CGContextRef)context size:(CGSize)size;
 
 @end
+NS_ASSUME_NONNULL_END
+
 #endif

package/native/appkit/RnTextLayout.mm

@@ -1,5 +1,10 @@
 #import "RnTextLayout.h"
 
+NSAttributedStringKey const RnWavyUnderlineAttributeName = @"RnWavyUnderline";
+
+#include "TextHighlight.h"
+#include "TextVerticalAlign.h"
+
 #include <cmath>
 
 @implementation RnTextLayout {
@@ -91,6 +96,25 @@
   return collected;
 }
 
+// The lines as ranges, which is the one thing accessibility needs and drawing
+// does not: a truncated last line reports the range it *shows*, so an index
+// past the ellipsis belongs to no line and is clamped to the last one by the
+// caller.
+- (NSArray<NSValue *> *)lineRangesForWidth:(CGFloat)maxWidth {
+  NSMutableArray *lines = [NSMutableArray array];
+  [self linesForWidth:maxWidth outLines:lines];
+  NSMutableArray<NSValue *> *ranges = [NSMutableArray arrayWithCapacity:lines.count];
+  for (id line in lines) {
+    const CFRange range = CTLineGetStringRange((__bridge CTLineRef)line);
+    if (range.location == kCFNotFound) {
+      continue;
+    }
+    [ranges addObject:[NSValue valueWithRange:NSMakeRange((NSUInteger)range.location,
+                                                          (NSUInteger)range.length)]];
+  }
+  return ranges;
+}
+
 // Line metrics, summed. Not CTFramesetterSuggestFrameSizeWithConstraints: that
 // measures the whole text and cannot be told about a line limit, so a
 // numberOfLines={2} paragraph would be laid out two lines tall and measured
@@ -111,6 +135,58 @@
   return CGSizeMake(std::ceil(width), height);
 }
 
+- (CGRect)frameForCharacterIndex:(NSUInteger)index width:(CGFloat)maxWidth {
+  NSMutableArray *lines = [NSMutableArray array];
+  [self linesForWidth:maxWidth outLines:lines];
+
+  // Walked the same way `sizeForWidth:` sums it, so a view's y agrees with the
+  // paragraph height the same layout reported. Duplicating the accumulation
+  // rather than sharing it would be the way these two drift apart.
+  CGFloat top = 0;
+  for (id item in lines) {
+    CTLineRef line = (__bridge CTLineRef)item;
+    CGFloat ascent = 0, descent = 0, leading = 0;
+    (void)CTLineGetTypographicBounds(line, &ascent, &descent, &leading);
+    const CGFloat lineHeight = std::ceil(ascent + descent + leading);
+
+    const CFRange range = CTLineGetStringRange(line);
+    const auto start = static_cast<NSUInteger>(range.location);
+    const auto length = static_cast<NSUInteger>(range.length);
+    if (index >= start && index < start + length) {
+      const CGFloat x = CTLineGetOffsetForStringIndex(line, static_cast<CFIndex>(index), nullptr);
+
+      // The run's own ascent and descent, not the line's: a short view on a line
+      // of tall text is its own height, and asking the line would give it the
+      // tallest thing on it. Found by the run whose range contains the index.
+      CGFloat runAscent = ascent;
+      CGFloat runDescent = descent;
+      CFArrayRef runs = CTLineGetGlyphRuns(line);
+      for (CFIndex r = 0; r < CFArrayGetCount(runs); r++) {
+        CTRunRef run = static_cast<CTRunRef>(CFArrayGetValueAtIndex(runs, r));
+        const CFRange runRange = CTRunGetStringRange(run);
+        const auto runStart = static_cast<NSUInteger>(runRange.location);
+        const auto runLength = static_cast<NSUInteger>(runRange.length);
+        if (index >= runStart && index < runStart + runLength) {
+          CTRunGetTypographicBounds(run, CFRangeMake(0, 0), &runAscent, &runDescent, nullptr);
+          break;
+        }
+      }
+
+      // Top-left, from a baseline-anchored box: the baseline sits `ascent` below
+      // the line's top, and the run rises `runAscent` above the baseline.
+      return CGRectMake(x,
+                        top + (ascent - runAscent),
+                        0,
+                        runAscent + runDescent);
+    }
+
+    top += lineHeight;
+  }
+
+  // Past the end, or dropped by a truncation.
+  return CGRectNull;
+}
+
 // How far along the line the text sits: 0 left, 0.5 centred, 1 right.
 //
 // Taken from the first fragment, because React Native resolves alignment onto
@@ -131,9 +207,194 @@
       return 0.5;
     case NSTextAlignmentRight:
       return 1.0;
-    default:
+    case NSTextAlignmentLeft:
+      // Explicitly left, which is not the same as natural: a right-to-left
+      // paragraph with `textAlign: 'left'` is flush left, and this used to fall
+      // through to the natural branch below and come out flush right.
       return 0;
+    default:
+      break;
   }
+
+  // What is left is `natural` and `justified`, and both mean the edge the
+  // paragraph *starts* from -- the relative alignments, `start` and `end`, were
+  // resolved into left or right before they got here; see
+  // core/TextAlignments.h.
+  //
+  // Which edge that is needs the paragraph's direction, and the style's own is
+  // only half of it: `NSWritingDirectionNatural` means "ask the text", which a
+  // frame would resolve and this does not use. `rightToLeft` is that answer,
+  // from core/TextDirection.h. Measured on both hosts and wrong on both at
+  // first: Pango flips a natural alignment only while it is deciding the
+  // direction itself, and Core Text only inside a frame. The two fixes are in
+  // different places and are the same decision. See PangoTextLayout.cpp.
+  if (_rightToLeft || style.baseWritingDirection == NSWritingDirectionRightToLeft) {
+    return 1.0;
+  }
+  return 0;
+}
+
+// `textAlignVertical`: where the paragraph sits in a box taller than it is. The
+// height the text needs is the one `sizeForWidth:` sums, walked the same way
+// here, so this asks the lines rather than measuring again.
+//
+// Its own method because the hit test needs the same number as the draw: a
+// paragraph sitting at the bottom of its box is hit-tested there too.
+- (CGFloat)verticalOffsetForSize:(CGSize)size lines:(NSArray *)lines {
+  if (self.verticalFlush <= 0) {
+    return 0;
+  }
+  CGFloat textHeight = 0;
+  for (id item in lines) {
+    CTLineRef line = (__bridge CTLineRef)item;
+    CGFloat ascent = 0, descent = 0, leading = 0;
+    (void)CTLineGetTypographicBounds(line, &ascent, &descent, &leading);
+    textHeight += std::ceil(ascent + descent + leading);
+  }
+  return (CGFloat)basalt::textVerticalOffset(size.height, textHeight, self.verticalFlush);
+}
+
+- (CGFloat)verticalOffsetForSize:(CGSize)size {
+  if (self.verticalFlush <= 0) {
+    // The common case, and worth answering without breaking the text into lines
+    // to do it: this is asked once per inline view per layout.
+    return 0;
+  }
+  NSMutableArray *lines = [NSMutableArray array];
+  [self linesForWidth:size.width outLines:lines];
+  return [self verticalOffsetForSize:size lines:lines];
+}
+
+- (NSUInteger)characterIndexAtPoint:(CGPoint)point size:(CGSize)size {
+  NSMutableArray *lines = [NSMutableArray array];
+  [self linesForWidth:size.width outLines:lines];
+  if (lines.count == 0) {
+    return 0;
+  }
+
+  // Which line the y falls in, walked the same way `sizeForWidth:` sums the
+  // heights so that a hit test and a measurement agree about where a line is.
+  // A point above the first line or below the last answers that line, which is
+  // what a drag off the top or the bottom of a paragraph means.
+  CGFloat top = [self verticalOffsetForSize:size lines:lines];
+  CTLineRef found = (__bridge CTLineRef)lines[0];
+  for (id item in lines) {
+    CTLineRef line = (__bridge CTLineRef)item;
+    CGFloat ascent = 0, descent = 0, leading = 0;
+    (void)CTLineGetTypographicBounds(line, &ascent, &descent, &leading);
+    const CGFloat height = std::ceil(ascent + descent + leading);
+    found = line;
+    if (point.y < top + height) {
+      break;
+    }
+    top += height;
+  }
+
+  // The x, in the line's own coordinates: a right-aligned or centred paragraph
+  // draws its lines offset, and the index at a point has to use the same
+  // offset the glyphs were drawn with.
+  const CGFloat flush = [self flushFactor];
+  const CGFloat lineX =
+      flush == 0 ? 0 : (CGFloat)CTLineGetPenOffsetForFlush(found, flush, size.width);
+  const CFIndex index =
+      CTLineGetStringIndexForPosition(found, CGPointMake(point.x - lineX, 0));
+  return index == kCFNotFound ? 0 : (NSUInteger)index;
+}
+
+- (nullable NSString *)selectedText {
+  if (_selection.length == 0 || _attributedString.length == 0) {
+    return nil;
+  }
+  // Clamped against the string rather than trusted: a paragraph can be rebuilt
+  // between a selection and a copy, and the old offsets would read past the end
+  // of a shorter one.
+  const NSUInteger length = _attributedString.length;
+  const NSUInteger start = MIN(_selection.location, length);
+  const NSUInteger end = MIN(start + _selection.length, length);
+  if (end <= start) {
+    return nil;
+  }
+  return [_attributedString.string substringWithRange:NSMakeRange(start, end - start)];
+}
+
+// One line's wavy underlines, stroked where the font says an underline goes.
+//
+// `baselineY` is this line's baseline in the context's current space, which
+// the caller has already flipped back into Core Text's y-up orientation.
+//
+// The wave is a run of quadratic curves rather than a dash pattern, which is
+// the one shape a stroke cannot express: amplitude and period are multiples of
+// the line's own thickness, so a 40pt squiggle has the same proportions as a
+// 12pt one. Browsers draw it at about this size.
+- (void)drawWavyUnderlinesForLine:(CTLineRef)line
+                          context:(CGContextRef)context
+                              atX:(CGFloat)originX
+                                y:(CGFloat)baselineY {
+  const CFRange lineRange = CTLineGetStringRange(line);
+  if (lineRange.location == kCFNotFound || lineRange.length <= 0) {
+    return;
+  }
+  const NSRange range = NSMakeRange((NSUInteger)lineRange.location, (NSUInteger)lineRange.length);
+  if (NSMaxRange(range) > _attributedString.length) {
+    return;
+  }
+
+  [_attributedString enumerateAttribute:RnWavyUnderlineAttributeName
+                                inRange:range
+                                options:0
+                             usingBlock:^(id value, NSRange found, BOOL *stop) {
+    (void)stop;
+    NSColor *color = [value isKindOfClass:[NSColor class]] ? (NSColor *)value : nil;
+    if (color == nil || found.length == 0) {
+      return;
+    }
+
+    // The font of the run the wave is under, so the line sits where that
+    // font's underline would have and is as thick as it would have been.
+    NSFont *font = [self->_attributedString attribute:NSFontAttributeName
+                                              atIndex:found.location
+                                       effectiveRange:nullptr];
+    const CGFloat thickness =
+        MAX((CGFloat)1.0, font != nil ? CTFontGetUnderlineThickness((__bridge CTFontRef)font) : 1.0);
+    const CGFloat position =
+        font != nil ? CTFontGetUnderlinePosition((__bridge CTFontRef)font) : -thickness * 2;
+
+    const CGFloat startX =
+        originX + CTLineGetOffsetForStringIndex(line, (CFIndex)found.location, nullptr);
+    const CGFloat endX =
+        originX + CTLineGetOffsetForStringIndex(line, (CFIndex)NSMaxRange(found), nullptr);
+    const CGFloat from = MIN(startX, endX);
+    const CGFloat to = MAX(startX, endX);
+    if (to - from < 1.0) {
+      return;
+    }
+
+    // The same geometry the Win32 renderer draws, down to the number that
+    // matters: quadratics alternating above and below the line, a half wave
+    // every six thicknesses, and a control point *twice* the amplitude away
+    // because a quadratic only reaches halfway to it. That host's comment
+    // records what happens otherwise -- a control point at one thickness
+    // draws a wave of half that, which measures as an edge moving two pixels
+    // where three were asked for -- and this host walked into it as well.
+    const CGFloat wave = thickness * 6.0;
+    const CGFloat middle = baselineY + position;
+
+    CGContextSaveGState(context);
+    CGContextSetStrokeColorWithColor(context, color.CGColor);
+    CGContextSetLineWidth(context, thickness);
+    CGContextSetLineCap(context, kCGLineCapRound);
+    CGContextBeginPath(context);
+    CGContextMoveToPoint(context, from, middle);
+    bool up = true;
+    for (CGFloat at = from; at < to; at += wave) {
+      const CGFloat next = MIN(at + wave, to);
+      const CGFloat peak = middle + 2.0 * (up ? thickness : -thickness);
+      CGContextAddQuadCurveToPoint(context, (at + next) / 2.0, peak, next, middle);
+      up = !up;
+    }
+    CGContextStrokePath(context);
+    CGContextRestoreGState(context);
+  }];
 }
 
 - (void)drawInContext:(CGContextRef)context size:(CGSize)size {
@@ -150,7 +411,22 @@
   CGContextScaleCTM(context, 1, -1);
   CGContextSetTextMatrix(context, CGAffineTransformIdentity);
 
-  CGFloat y = size.height;
+  // The text shadow, on the context: Core Text ignores an NSShadow attribute,
+  // and one shadow for the paragraph is what core/TextShadows.h resolves anyway.
+  //
+  // The offset's y is negated because the context has just been flipped back to
+  // Core Text's orientation, where y grows upward: React Native means a positive
+  // offset as *down* the screen, which is what the GTK side gets for free.
+  if (self.shadowColor != nil) {
+    CGContextSetShadowWithColor(context,
+                                CGSizeMake(self.shadowOffset.width, -self.shadowOffset.height),
+                                self.shadowStandardDeviation,
+                                self.shadowColor.CGColor);
+  }
+
+  // Core Text's y grows upward and the context has just been flipped back into
+  // that, so moving the paragraph *down* the box means starting lower.
+  CGFloat y = size.height - [self verticalOffsetForSize:size lines:lines];
   for (id item in lines) {
     CTLineRef line = (__bridge CTLineRef)item;
     CGFloat ascent = 0, descent = 0, leading = 0;
@@ -158,6 +434,49 @@
 
     y -= std::ceil(ascent + descent + leading);
     const CGFloat x = flush == 0 ? 0 : (CGFloat)CTLineGetPenOffsetForFlush(line, flush, size.width);
+
+    // The selection, under this line's glyphs and before them: a wash rather
+    // than a solid fill, because nothing recolours the text and it has to stay
+    // legible through it. See core/TextHighlight.h for why the colour is this
+    // project's rather than the system's.
+    if (_selection.length > 0) {
+      const CFRange lineRange = CTLineGetStringRange(line);
+      const NSUInteger lineStart = (NSUInteger)lineRange.location;
+      const NSUInteger lineEnd = lineStart + (NSUInteger)lineRange.length;
+      const NSUInteger from = MAX(_selection.location, lineStart);
+      const NSUInteger to = MIN(_selection.location + _selection.length, lineEnd);
+      if (to > from) {
+        // Two offsets along the line, which is where a bidirectional line needs
+        // more than one rectangle -- a selection contiguous in the string is not
+        // contiguous on the line. Taking the span between the two offsets is one
+        // rectangle and is what iOS's own `UITextView` draws for the common
+        // case; the mixed-direction case is recorded in backlog/text.md.
+        const CGFloat startX = CTLineGetOffsetForStringIndex(line, (CFIndex)from, nullptr);
+        const CGFloat endX = CTLineGetOffsetForStringIndex(line, (CFIndex)to, nullptr);
+        const CGRect wash = CGRectMake(x + MIN(startX, endX),
+                                       y,
+                                       std::abs(endX - startX),
+                                       std::ceil(ascent + descent + leading));
+        CGContextSaveGState(context);
+        CGContextSetRGBFillColor(context,
+                                 basalt::kTextSelectionRed,
+                                 basalt::kTextSelectionGreen,
+                                 basalt::kTextSelectionBlue,
+                                 basalt::kTextSelectionAlpha);
+        CGContextFillRect(context, wash);
+        CGContextRestoreGState(context);
+      }
+    }
+
+    // The squiggle Core Text has no pattern for, under this line's glyphs and
+    // before them: an underline goes beneath the text, and a descender
+    // crossing it is drawn on top the way a straight underline's is. See
+    // RnWavyUnderlineAttributeName.
+    [self drawWavyUnderlinesForLine:line
+                            context:context
+                                atX:x
+                                  y:y + std::ceil(descent + leading)];
+
     CGContextSetTextPosition(context, x, y + std::ceil(descent + leading));
     CTLineDraw(line, context);
   }