@rafaelaugusto/jolt 0.1.0-beta.1 → 0.1.0-beta.10

package/src/text-layout.ts

@@ -0,0 +1,228 @@
+/** TextKit lays out the complete string before any glyphs are separated. */
+type Insets = { top: number; left: number; bottom: number; right: number }
+type NativeLabel = UILabel & { padding?: Insets; borderThickness?: Insets }
+/** The characters one piece draws, as UTF-16 offsets into the label text. */
+export interface TextPiece {
+  text: string
+  location: number
+  length: number
+}
+const MAX_PIECES = 256
+const MAX_PIXELS = 4_000_000
+
+/** Ligatures and composed characters may share glyphs. Never draw a shared glyph twice. */
+export function mergeGlyphRanges(ranges: readonly NSRange[]): NSRange[] {
+  const merged: NSRange[] = []
+  for (const range of ranges) {
+    if (!range.length) continue
+    const previous = merged.at(-1)
+    if (
+      previous &&
+      range.location < previous.location + previous.length &&
+      range.location + range.length > previous.location
+    ) {
+      const end = Math.max(
+        previous.location + previous.length,
+        range.location + range.length,
+      )
+      previous.location = Math.min(previous.location, range.location)
+      previous.length = end - previous.location
+    } else merged.push({ location: range.location, length: range.length })
+  }
+  return merged
+}
+
+export function textLayer(native: NativeLabel, by: 'letter' | 'word') {
+  if (native.adjustsFontSizeToFitWidth) return undefined
+  const original = native.attributedText
+  const text = original?.string ?? native.text ?? ''
+  if (!text.trim()) return { text, layer: undefined, pieces: [] as TextPiece[] }
+  const string = NSString.stringWithString(text)
+  const full = { location: 0, length: string.length }
+  const attributed = original
+    ? NSMutableAttributedString.alloc().initWithAttributedString(original)
+    : NSMutableAttributedString.alloc().initWithString(text)
+  const paragraph = NSMutableParagraphStyle.new()
+  paragraph.alignment = native.textAlignment
+  paragraph.lineBreakMode = native.lineBreakMode
+  const defaults: [string, unknown][] = [
+    [NSFontAttributeName, native.font],
+    [NSForegroundColorAttributeName, native.textColor],
+    [NSParagraphStyleAttributeName, paragraph],
+  ]
+  if (native.shadowColor) {
+    const shadow = NSShadow.new()
+    shadow.shadowColor = native.shadowColor
+    shadow.shadowOffset = native.shadowOffset
+    defaults.push([NSShadowAttributeName, shadow])
+  }
+  for (const [key, value] of defaults) {
+    attributed.enumerateAttributeInRangeOptionsUsingBlock(
+      key,
+      full,
+      0 as NSAttributedStringEnumerationOptions,
+      (attribute, range) => {
+        if (attribute == null && value != null)
+          attributed.addAttributeValueRange(key, value, range)
+      },
+    )
+  }
+  const inset = (side: keyof Insets) =>
+    (native.padding?.[side] ?? 0) + (native.borderThickness?.[side] ?? 0)
+  const bounds = native.bounds
+  const width = bounds.size.width - inset('left') - inset('right')
+  const height = bounds.size.height - inset('top') - inset('bottom')
+  if (width <= 0 || height <= 0) return undefined
+  const storage = NSTextStorage.alloc().initWithAttributedString(attributed)
+  const manager = NSLayoutManager.new()
+  manager.usesFontLeading = false
+  const container = NSTextContainer.alloc().initWithSize(CGSizeMake(width, height))
+  container.lineFragmentPadding = 0
+  container.maximumNumberOfLines = native.numberOfLines
+  container.lineBreakMode = native.lineBreakMode
+  manager.addTextContainer(container)
+  storage.addLayoutManager(manager)
+  manager.ensureLayoutForTextContainer(container)
+  const visible = manager.glyphRangeForTextContainer(container)
+  if (visible.length !== manager.numberOfGlyphs) return undefined
+  // A truncation token is not an independently addressable character. Keep the real label.
+  for (let glyph = 0; glyph < manager.numberOfGlyphs;) {
+    if (manager.truncatedGlyphRangeInLineFragmentForGlyphAtIndex(glyph).length)
+      return undefined
+    const range = new interop.Reference<NSRange>()
+    manager.lineFragmentRectForGlyphAtIndexEffectiveRange(glyph, range)
+    const next = range.value.location + range.value.length
+    if (next <= glyph) return undefined
+    glyph = next
+  }
+  const characters: NSRange[] = []
+  string.enumerateSubstringsInRangeOptionsUsingBlock(
+    full,
+    by === 'letter' ? 2 : 3,
+    (substring, range) => {
+      if (substring?.trim())
+        characters.push({ location: range.location, length: range.length })
+    },
+  )
+  if (by === 'word') {
+    // Attach spaces and punctuation to the surrounding word, preserving every visible mark.
+    characters.forEach((range, index) => {
+      const start = index === 0 ? 0 : range.location
+      const end = characters[index + 1]?.location ?? full.length
+      range.location = start
+      range.length = end - start
+    })
+    if (!characters.length) characters.push(full)
+  }
+  const ranges = mergeGlyphRanges(
+    characters.map((range) =>
+      manager.glyphRangeForCharacterRangeActualCharacterRange(range, null),
+    ),
+  )
+  if (ranges.length > MAX_PIECES) return undefined
+  const used = manager.usedRectForTextContainer(container)
+  const offsetX = bounds.origin.x + inset('left')
+  const offsetY =
+    bounds.origin.y + inset('top') + (height - used.size.height) / 2 - used.origin.y
+  const scale = native.window?.screen.scale ?? UIScreen.mainScreen.scale
+  const padding = Math.max(4, native.font.pointSize * 0.1)
+  const pieces = ranges.map((range) => {
+    const glyph = manager.boundingRectForGlyphRangeInTextContainer(range, container)
+    return {
+      range,
+      rect: CGRectIntegral(
+        CGRectMake(
+          glyph.origin.x + offsetX - padding,
+          glyph.origin.y + offsetY - padding,
+          glyph.size.width + padding * 2,
+          glyph.size.height + padding * 2,
+        ),
+      ),
+    }
+  })
+  if (
+    pieces.reduce(
+      (pixels, { rect }) => pixels + rect.size.width * rect.size.height * scale * scale,
+      0,
+    ) > MAX_PIXELS
+  )
+    return undefined
+  const layer = CALayer.new()
+  layer.name = 'jolt:text'
+  layer.frame = bounds
+  const transparent = UIColor.clearColor
+  const noShadow = NSShadow.new()
+  noShadow.shadowColor = transparent
+  const hidden = NSMutableAttributedString.alloc().initWithAttributedString(attributed)
+  for (const key of [
+    NSForegroundColorAttributeName,
+    NSBackgroundColorAttributeName,
+    NSUnderlineColorAttributeName,
+    NSStrikethroughColorAttributeName,
+    NSStrokeColorAttributeName,
+  ]) {
+    hidden.addAttributeValueRange(key, transparent, full)
+  }
+  hidden.addAttributeValueRange(NSShadowAttributeName, noShadow, full)
+  let attachments = false
+  attributed.enumerateAttributeInRangeOptionsUsingBlock(
+    NSAttachmentAttributeName,
+    full,
+    0 as NSAttributedStringEnumerationOptions,
+    (value) => {
+      if (value != null) attachments = true
+    },
+  )
+  if (attachments) return undefined
+  const shadowColor = native.shadowColor
+  const drawn: TextPiece[] = []
+  try {
+    native.shadowColor = null
+    for (const { range, rect } of pieces) {
+      const fragment = NSMutableAttributedString.alloc().initWithAttributedString(hidden)
+      const characters = manager.characterRangeForGlyphRangeActualGlyphRange(range, null)
+      drawn.push({
+        text: string.substringWithRange(characters),
+        location: characters.location,
+        length: characters.length,
+      })
+      attributed.enumerateAttributesInRangeOptionsUsingBlock(
+        characters,
+        0 as NSAttributedStringEnumerationOptions,
+        (attributes, part) => fragment.setAttributesRange(attributes, part),
+      )
+      native.attributedText = fragment
+      // UILabel draws its own glyphs, preserving its baseline rounding and fallback-font metrics.
+      // Other glyphs keep their shaping/advances but have transparent paint.
+      UIGraphicsBeginImageContextWithOptions(rect.size, false, scale)
+      let image: UIImage | null
+      try {
+        CGContextTranslateCTM(
+          UIGraphicsGetCurrentContext()!,
+          -rect.origin.x,
+          -rect.origin.y,
+        )
+        native.drawTextInRect(bounds)
+        image = UIGraphicsGetImageFromCurrentImageContext()
+      } finally {
+        UIGraphicsEndImageContext()
+      }
+      if (!image?.CGImage) return undefined
+      const piece = CALayer.new()
+      piece.frame = CGRectMake(
+        rect.origin.x - bounds.origin.x,
+        rect.origin.y - bounds.origin.y,
+        rect.size.width,
+        rect.size.height,
+      )
+      piece.contents = image.CGImage
+      piece.contentsScale = scale
+      layer.addSublayer(piece)
+    }
+  } finally {
+    if (original) native.attributedText = original
+    else native.text = text
+    native.shadowColor = shadowColor
+  }
+  return { text, layer, pieces: drawn }
+}

package/src/text.ts

@@ -0,0 +1,279 @@
+import { stopIOSColorText } from './driver/ios-color.js'
+import { Application, Label, Utils, isAndroid, isIOS } from '@nativescript/core'
+import { textProperty, formattedTextProperty } from '@nativescript/core/ui/text-base'
+import { toView } from './animate.js'
+import { reducedMotion, timeScale } from './config.js'
+import type { Animation } from './engine.js'
+import { completion, forgetCompletion, watchLabel } from './label.js'
+import { textLayer } from './text-layout.js'
+import type { Target } from './types.js'
+
+export interface TextOptions {
+  /** Composed letters (including emoji), or words. Defaults to 'letter'. */
+  by?: 'letter' | 'word'
+  /** Milliseconds per piece. Defaults to 400. */
+  duration?: number
+  /** Milliseconds between pieces. Defaults to 35. */
+  stagger?: number
+  /** Milliseconds before the first piece. Defaults to zero. */
+  delay?: number
+  /** Initial vertical offset in DIPs. Defaults to 12. */
+  y?: number
+}
+type Options = Required<TextOptions>
+const running = new WeakMap<Label, TextAnimation>()
+
+/** Reveals the text of a Label without splitting its layout or accessibility element. */
+export function animateText(target: Target, options: TextOptions = {}): Animation {
+  const config: Options = {
+    by: options.by ?? 'letter',
+    duration: options.duration ?? 400,
+    stagger: options.stagger ?? 35,
+    delay: options.delay ?? 0,
+    y: options.y ?? 12,
+  }
+  if (config.by !== 'letter' && config.by !== 'word')
+    throw new TypeError('Text grouping must be letter or word.')
+  for (const key of ['duration', 'stagger', 'delay'] as const) {
+    if (!Number.isFinite(config[key]) || config[key] < 0)
+      throw new RangeError(`Text ${key} must be a nonnegative finite number.`)
+  }
+  if (!Number.isFinite(config.y)) throw new RangeError('Text y must be finite.')
+  const view = toView(target)
+  if (!(view instanceof Label)) throw new TypeError('Expected a NativeScript Label.')
+  running.get(view)?.stop()
+  return new TextAnimation(view, config)
+}
+
+class TextAnimation implements Animation {
+  readonly finished: Promise<boolean>
+  private resolve!: (finished: boolean) => void
+  private settled = false
+  private queued = false
+  private native: UILabel | android.widget.TextView | undefined
+  private reveal: org.rafaelaugusto.jolt.TextReveal | undefined
+  private unwatch: (() => void) | undefined
+  private bounds: CGRect | undefined
+  private layer: CALayer | undefined
+  private originalText: string | null = null
+  private originalAttributed: NSAttributedString | null = null
+  private accessibility: string | null = null
+  private temporaryAccessibility: string | undefined
+  private delegate: NSObject | undefined
+  private observer: ReturnType<typeof Application.ios.addNotificationObserver> | undefined
+
+  constructor(
+    private readonly view: Label,
+    private readonly options: Options,
+  ) {
+    this.finished = new Promise((resolve) => {
+      this.resolve = resolve
+    })
+    if (isIOS) stopIOSColorText(view)
+    running.set(view, this)
+    if (!isIOS && !isAndroid) {
+      this.end(false)
+      return
+    }
+    if (options.duration === 0 || reducedMotion()) {
+      this.end(true)
+      return
+    }
+    view.on('loaded', this.schedule)
+    view.on('layoutChanged', this.layoutChanged)
+    view.on('unloaded', this.stop)
+    this.unwatch = watchLabel(view, this.changed)
+    this.schedule()
+  }
+
+  then<A = boolean, B = never>(
+    onfulfilled?: ((finished: boolean) => A | PromiseLike<A>) | null,
+    onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null,
+  ): Promise<A | B> {
+    return this.finished.then(onfulfilled, onrejected)
+  }
+  /** Cancels the entrance and restores the full text. */
+  stop = () => this.end(false)
+  private changed = () => this.end(false, true)
+  private motionChanged = () => {
+    if (reducedMotion()) this.end(true)
+  }
+  private layoutChanged = () => {
+    if (isAndroid) {
+      if (!this.reveal) this.schedule()
+      else if (this.view.nativeViewProtected !== this.native) this.stop()
+      return
+    }
+    const native = this.view.nativeViewProtected as UILabel | undefined
+    const a = this.bounds
+    const b = native?.bounds
+    if (
+      this.layer &&
+      (native !== this.native ||
+        !native?.window ||
+        !b ||
+        !a ||
+        a.origin.x !== b.origin.x ||
+        a.origin.y !== b.origin.y ||
+        a.size.width !== b.size.width ||
+        a.size.height !== b.size.height)
+    )
+      return this.stop()
+    this.schedule()
+  }
+  private schedule = () => {
+    if (this.settled || this.queued) return
+    this.queued = true
+    void Promise.resolve().then(() => {
+      this.queued = false
+      if (this.settled || this.layer || this.reveal || !this.view.isLoaded) return
+      try {
+        this.start()
+      } catch {
+        this.end(false)
+      }
+    })
+  }
+  private start() {
+    if (this.options.duration === 0 || reducedMotion()) return this.end(true)
+    if (this.view.visibility !== 'visible') return this.end(false)
+    if (isAndroid) return this.startAndroid()
+    const native = this.view.nativeViewProtected as UILabel | undefined
+    if (!(native instanceof UILabel) || !native.window) return
+    if (native.bounds.size.width <= 0 || native.bounds.size.height <= 0) return
+    const prepared = textLayer(native, this.options.by)
+    if (!prepared) return this.end(false)
+    if (!prepared.layer?.sublayers?.count) return this.end(true)
+    const slowdown = 1 / timeScale()
+    const duration = this.options.duration * slowdown
+    const stagger = this.options.stagger * slowdown
+    const delay = this.options.delay * slowdown
+    if (
+      !Number.isFinite(delay + duration + (prepared.layer.sublayers.count - 1) * stagger)
+    )
+      return this.end(false)
+    this.native = native
+    this.bounds = native.bounds
+    this.layer = prepared.layer
+    this.originalText = native.text
+    this.originalAttributed = native.attributedText
+    this.accessibility = native.accessibilityLabel
+    this.temporaryAccessibility = this.accessibility ?? prepared.text
+    const { y } = this.options
+    const start = CACurrentMediaTime()
+    CATransaction.begin()
+    CATransaction.setDisableActions(true)
+    try {
+      native.text = ''
+      native.accessibilityLabel = this.temporaryAccessibility
+      native.layer.addSublayer(this.layer)
+      const pieces = this.layer.sublayers!
+      for (let i = 0; i < pieces.count; i++) {
+        const piece = pieces.objectAtIndex(i)
+        const fade = CABasicAnimation.animationWithKeyPath('opacity')
+        fade.fromValue = 0
+        fade.toValue = 1
+        const move = CABasicAnimation.animationWithKeyPath('transform.translation.y')
+        move.fromValue = y
+        move.toValue = 0
+        fade.duration = move.duration = duration / 1000
+        const group = CAAnimationGroup.new()
+        group.animations = NSArray.arrayWithArray([fade, move])
+        group.duration = duration / 1000
+        group.beginTime = start + (delay + i * stagger) / 1000
+        group.fillMode = kCAFillModeBackwards
+        group.timingFunction = CAMediaTimingFunction.functionWithName(
+          kCAMediaTimingFunctionEaseOut,
+        )
+        if (i === pieces.count - 1)
+          this.delegate = group.delegate = completion((finished) => this.end(finished))
+        piece.addAnimationForKey(group, 'jolt:text')
+      }
+      this.observer = Application.ios.addNotificationObserver(
+        UIAccessibilityReduceMotionStatusDidChangeNotification,
+        this.motionChanged,
+      )
+    } finally {
+      CATransaction.commit()
+    }
+  }
+  private startAndroid() {
+    const native = this.view.nativeViewProtected as android.widget.TextView | undefined
+    if (!(native instanceof android.widget.TextView)) return this.end(false)
+    const { by, duration, stagger, delay, y } = this.options
+    let reveal: org.rafaelaugusto.jolt.TextReveal
+    try {
+      reveal = new org.rafaelaugusto.jolt.TextReveal(
+        native,
+        by === 'word',
+        Math.round(duration),
+        Math.round(stagger),
+        Math.round(delay),
+        y * Utils.layout.getDisplayDensity(),
+        new org.rafaelaugusto.jolt.TextReveal.Callback({
+          onEnd: (finished: boolean) => {
+            if (this.reveal !== reveal) return
+            this.reveal = undefined
+            this.end(finished)
+          },
+        }),
+      )
+    } catch {
+      // A JS-only update cannot install the native plugin. Keep the label as it is.
+      return this.end(false)
+    }
+    if (!reveal.isSupported()) return this.end(false)
+    this.native = native
+    this.reveal = reveal
+    reveal.start()
+  }
+  private end(finished: boolean, refresh = false) {
+    if (this.settled) return
+    this.settled = true
+    const { view, layer } = this
+    const native = this.native as UILabel | undefined
+    const reveal = this.reveal
+    this.reveal = undefined
+    reveal?.cancel()
+    view.off('loaded', this.schedule)
+    view.off('layoutChanged', this.layoutChanged)
+    view.off('unloaded', this.stop)
+    this.unwatch?.()
+    if (running.get(view) === this) running.delete(view)
+    if (this.observer)
+      Application.ios.removeNotificationObserver(
+        this.observer,
+        UIAccessibilityReduceMotionStatusDidChangeNotification,
+      )
+    if (this.delegate) forgetCompletion(this.delegate)
+    if (native && layer) {
+      CATransaction.begin()
+      CATransaction.setDisableActions(true)
+      try {
+        // Restore only the native text we suppressed; app changes win.
+        if (!native.text && !native.attributedText?.length) {
+          if (refresh && view.nativeViewProtected === native) {
+            const property = view.formattedText ? formattedTextProperty : textProperty
+            ;(view as unknown as Record<symbol, (value: unknown) => void>)[
+              property.setNative
+            ]!(view.formattedText ?? view.text)
+          } else if (this.originalAttributed)
+            native.attributedText = this.originalAttributed
+          else native.text = this.originalText
+        }
+        if (native.accessibilityLabel === this.temporaryAccessibility)
+          native.accessibilityLabel = this.accessibility
+        layer.removeFromSuperlayer()
+        const pieces = layer.sublayers
+        if (pieces)
+          for (let i = 0; i < pieces.count; i++)
+            pieces.objectAtIndex(i).removeAnimationForKey('jolt:text')
+      } finally {
+        CATransaction.commit()
+      }
+    }
+    this.native = this.layer = this.delegate = this.observer = undefined
+    this.originalAttributed = null
+    this.resolve(finished)
+  }
+}