expo-pretext 0.2.0

package/src/hooks/useFlashListHeights.ts

@@ -0,0 +1,88 @@
+import { useMemo, useEffect, useRef, useCallback } from 'react'
+import { getNativeModule } from '../ExpoPretext'
+import { textStyleToFontDescriptor, getLineHeight } from '../font-utils'
+import { prepare } from '../prepare'
+import { layout } from '../layout'
+import type { TextStyle } from '../types'
+
+type FlashListLayoutResult = {
+  estimatedItemSize: number
+  overrideItemLayout: (layout: { size?: number }, item: any, index: number) => void
+}
+
+// Measure single text height — TextKit primary, segment fallback
+function measureSingleHeight(text: string, style: TextStyle, maxWidth: number): number {
+  const native = getNativeModule()
+  if (native) {
+    try {
+      const font = textStyleToFontDescriptor(style)
+      const lh = getLineHeight(style)
+      return native.measureTextHeight(text, font, maxWidth, lh).height
+    } catch {}
+  }
+  // Fallback: segment-based
+  const prepared = prepare(text, style)
+  return layout(prepared, maxWidth).height
+}
+
+export function useFlashListHeights<T>(
+  data: T[],
+  getText: (item: T) => string,
+  style: TextStyle,
+  maxWidth: number
+): FlashListLayoutResult {
+  const heightsRef = useRef<Map<string, number>>(new Map())
+  const lineHeight = getLineHeight(style)
+
+  // Pre-warm cache
+  useEffect(() => {
+    const texts = data.map(getText)
+    const batchSize = 50
+    let offset = 0
+
+    function warmNext() {
+      const batch = texts.slice(offset, offset + batchSize)
+      if (batch.length === 0) return
+
+      for (const text of batch) {
+        if (!heightsRef.current.has(text)) {
+          heightsRef.current.set(text, measureSingleHeight(text, style, maxWidth))
+        }
+      }
+
+      offset += batchSize
+      if (typeof requestIdleCallback !== 'undefined' && offset < texts.length) {
+        requestIdleCallback(warmNext)
+      }
+    }
+
+    if (typeof requestIdleCallback !== 'undefined') {
+      requestIdleCallback(warmNext)
+    } else {
+      for (const text of texts) {
+        if (!heightsRef.current.has(text)) {
+          heightsRef.current.set(text, measureSingleHeight(text, style, maxWidth))
+        }
+      }
+    }
+  }, [data.length, getText, style.fontFamily, style.fontSize, maxWidth])
+
+  const estimatedItemSize = useMemo(() => lineHeight * 2, [lineHeight])
+
+  const overrideItemLayout = useCallback(
+    (layoutObj: { size?: number }, item: T, _index: number) => {
+      const text = getText(item)
+      const cached = heightsRef.current.get(text)
+      if (cached !== undefined) {
+        layoutObj.size = cached
+        return
+      }
+      const height = measureSingleHeight(text, style, maxWidth)
+      heightsRef.current.set(text, height)
+      layoutObj.size = height
+    },
+    [getText, style, maxWidth]
+  )
+
+  return { estimatedItemSize, overrideItemLayout }
+}

package/src/hooks/usePreparedText.ts

@@ -0,0 +1,16 @@
+import { useMemo } from 'react'
+import { prepare } from '../prepare'
+import type { TextStyle, PreparedText, PrepareOptions } from '../types'
+
+export function usePreparedText(
+  text: string,
+  style: TextStyle,
+  options?: PrepareOptions
+): PreparedText | null {
+  return useMemo(() => {
+    if (!text) return null
+    return prepare(text, style, options)
+  }, [text, style.fontFamily, style.fontSize, style.fontWeight,
+      style.fontStyle, style.lineHeight,
+      options?.whiteSpace, options?.locale, options?.accuracy])
+}

package/src/hooks/useTextHeight.ts

@@ -0,0 +1,45 @@
+import { useRef, useMemo } from 'react'
+import { getNativeModule } from '../ExpoPretext'
+import { textStyleToFontDescriptor, getLineHeight } from '../font-utils'
+import { prepareStreaming } from '../streaming'
+import { layout } from '../layout'
+import type { TextStyle, PrepareOptions } from '../types'
+
+export function useTextHeight(
+  text: string,
+  style: TextStyle,
+  maxWidth: number,
+  options?: PrepareOptions
+): number {
+  const keyRef = useRef({})
+
+  return useMemo(() => {
+    if (!text) return 0
+
+    // Primary: TextKit (NSLayoutManager) — pixel-perfect match with RN Text
+    const native = getNativeModule()
+    if (native) {
+      try {
+        const font = textStyleToFontDescriptor(style)
+        const lh = getLineHeight(style)
+        const result = native.measureTextHeight(text, font, maxWidth, lh)
+        return result.height
+      } catch {
+        // Fall through to segment-based
+      }
+    }
+
+    // Fallback: segment-based prepare + layout
+    try {
+      const prepared = prepareStreaming(keyRef.current, text, style, options)
+      return layout(prepared, maxWidth).height
+    } catch {
+      // Last resort: rough estimate
+      const lh = getLineHeight(style)
+      const charsPerLine = Math.max(1, maxWidth / (style.fontSize * 0.5))
+      return Math.ceil(text.length / charsPerLine) * lh
+    }
+  }, [text, style.fontFamily, style.fontSize, style.fontWeight,
+      style.fontStyle, style.lineHeight, maxWidth,
+      options?.whiteSpace, options?.locale, options?.accuracy])
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+// src/index.ts
+// Public API for expo-pretext.
+// Simple API (hooks) + Power API (Pretext 1:1) + Utilities.
+
+// --- Types ---
+export type {
+  TextStyle,
+  PrepareOptions,
+  PreparedText,
+  PreparedTextWithSegments,
+  LayoutResult,
+  LayoutLine,
+  LayoutLineRange,
+  LayoutCursor,
+  LayoutWithLinesResult,
+  InlineFlowItem,
+  PreparedInlineFlow,
+  InlineFlowCursor,
+  InlineFlowFragment,
+  InlineFlowLine,
+} from './types'
+
+// --- Simple API ---
+export { useTextHeight } from './hooks/useTextHeight'
+export { usePreparedText } from './hooks/usePreparedText'
+export { useFlashListHeights } from './hooks/useFlashListHeights'
+export { measureHeights } from './prepare'
+
+// --- Core API ---
+export { prepare, prepareWithSegments } from './prepare'
+export { layout, layoutWithLines, layoutNextLine, walkLineRanges, measureNaturalWidth } from './layout'
+
+// --- Rich Inline (formerly inline-flow) ---
+export { prepareInlineFlow, walkInlineFlowLines, measureInlineFlow } from './rich-inline'
+
+// --- Obstacle Layout ---
+export {
+  carveTextLineSlots,
+  circleIntervalForBand,
+  rectIntervalForBand,
+  layoutColumn,
+} from './obstacle-layout'
+export type {
+  Interval,
+  CircleObstacle,
+  RectObstacle,
+  LayoutRegion,
+  PositionedLine,
+  LayoutColumnResult,
+} from './obstacle-layout'
+
+// --- Streaming ---
+export { prepareStreaming, clearStreamingState } from './streaming'
+
+// --- Utilities ---
+export { clearCache, setLocale } from './layout'

package/src/layout.ts

@@ -0,0 +1,353 @@
+// Layout engine for expo-pretext, ported from chenglou/pretext src/layout.ts.
+//
+// The line-breaking algorithm, line walking, and all layout math are unchanged
+// from Pretext. The public API surface is preserved:
+//   layout(prepared, maxWidth)           -> { height, lineCount }
+//   layoutWithLines(prepared, maxWidth)  -> { height, lineCount, lines }
+//   layoutNextLine(prepared, start, maxWidth) -> LayoutLine | null
+//   walkLineRanges(prepared, maxWidth, onLine) -> number
+//   measureNaturalWidth(prepared)        -> number
+//   clearCache()                         — clears internal + JS caches
+//   setLocale(locale?)                   — sets locale for analysis
+
+import {
+  clearAnalysisCaches,
+  setAnalysisLocale,
+  type SegmentBreakKind,
+} from './analysis'
+import {
+  countPreparedLines,
+  layoutNextLineRange as stepPreparedLineRange,
+  measurePreparedLineGeometry,
+  walkPreparedLines,
+  type InternalLayoutLine,
+} from './line-break'
+import { clearJSCache } from './cache'
+import {
+  getSharedGraphemeSegmenter,
+  clearGraphemeSegmenter,
+  type InternalPreparedText,
+  type InternalPreparedTextWithSegments,
+} from './build'
+import type {
+  TextStyle,
+  LayoutCursor,
+  LayoutResult,
+  LayoutLine,
+  LayoutLineRange,
+  PreparedText,
+  PreparedTextWithSegments as PublicPreparedTextWithSegments,
+} from './types'
+
+// Re-export build functions so existing consumers (prepare.ts, tests) can
+// still import from layout.ts during migration. The canonical source is build.ts.
+export { buildPreparedText, buildPreparedTextWithSegments } from './build'
+export type { PreparedLineChunk, PrepareOptions } from './build'
+
+// Rich-path only. Reuses grapheme splits while materializing multiple lines
+// from the same prepared handle, without pushing that cache into the API.
+let sharedLineTextCaches = new WeakMap<InternalPreparedTextWithSegments, Map<number, string[]>>()
+
+export type LineGeometry = {
+  lineCount: number
+  maxLineWidth: number
+}
+
+export type LayoutLinesResult = LayoutResult & {
+  lines: LayoutLine[]
+}
+
+// --- Internal helpers for public API ---
+
+function getInternalPrepared(prepared: PreparedText): InternalPreparedText {
+  return prepared as InternalPreparedText
+}
+
+function getInternalPreparedWithSegments(prepared: PublicPreparedTextWithSegments): InternalPreparedTextWithSegments {
+  return prepared as unknown as InternalPreparedTextWithSegments
+}
+
+function resolveLineHeight(prepared: InternalPreparedText, lineHeightOverride?: number): number {
+  if (lineHeightOverride !== undefined) return lineHeightOverride
+  const style = prepared.style
+  if (style !== null && style.lineHeight !== undefined) return style.lineHeight
+  if (style !== null) return style.fontSize * 1.2
+  return 0
+}
+
+// --- Public layout API ---
+
+// Layout prepared text at a given max width. Pure arithmetic on cached widths —
+// no native calls, no string operations, no allocations.
+// ~0.0002ms per text block. Call on every resize.
+//
+// lineHeight is optional: if omitted, it is read from the prepared handle's
+// TextStyle (style.lineHeight, or fontSize * 1.2 as fallback).
+export function layout(prepared: PreparedText, maxWidth: number, lineHeight?: number): LayoutResult {
+  const internal = getInternalPrepared(prepared)
+  const lineCount = countPreparedLines(internal, maxWidth)
+  const lh = resolveLineHeight(internal, lineHeight)
+  return { lineCount, height: lineCount * lh }
+}
+
+function getSegmentGraphemes(
+  segmentIndex: number,
+  segments: string[],
+  cache: Map<number, string[]>,
+): string[] {
+  let graphemes = cache.get(segmentIndex)
+  if (graphemes !== undefined) return graphemes
+
+  graphemes = []
+  const graphemeSegmenter = getSharedGraphemeSegmenter()
+  for (const gs of graphemeSegmenter.segment(segments[segmentIndex]!)) {
+    graphemes.push(gs.segment)
+  }
+  cache.set(segmentIndex, graphemes)
+  return graphemes
+}
+
+function getLineTextCache(prepared: InternalPreparedTextWithSegments): Map<number, string[]> {
+  let cache = sharedLineTextCaches.get(prepared)
+  if (cache !== undefined) return cache
+
+  cache = new Map<number, string[]>()
+  sharedLineTextCaches.set(prepared, cache)
+  return cache
+}
+
+function lineHasDiscretionaryHyphen(
+  kinds: SegmentBreakKind[],
+  startSegmentIndex: number,
+  startGraphemeIndex: number,
+  endSegmentIndex: number,
+): boolean {
+  return (
+    endSegmentIndex > 0 &&
+    kinds[endSegmentIndex - 1] === 'soft-hyphen' &&
+    !(startSegmentIndex === endSegmentIndex && startGraphemeIndex > 0)
+  )
+}
+
+function buildLineTextFromRange(
+  segments: string[],
+  kinds: SegmentBreakKind[],
+  cache: Map<number, string[]>,
+  startSegmentIndex: number,
+  startGraphemeIndex: number,
+  endSegmentIndex: number,
+  endGraphemeIndex: number,
+): string {
+  let text = ''
+  const endsWithDiscretionaryHyphen = lineHasDiscretionaryHyphen(
+    kinds,
+    startSegmentIndex,
+    startGraphemeIndex,
+    endSegmentIndex,
+  )
+
+  for (let i = startSegmentIndex; i < endSegmentIndex; i++) {
+    if (kinds[i] === 'soft-hyphen' || kinds[i] === 'hard-break') continue
+    if (i === startSegmentIndex && startGraphemeIndex > 0) {
+      text += getSegmentGraphemes(i, segments, cache).slice(startGraphemeIndex).join('')
+    } else {
+      text += segments[i]!
+    }
+  }
+
+  if (endGraphemeIndex > 0) {
+    if (endsWithDiscretionaryHyphen) text += '-'
+    text += getSegmentGraphemes(endSegmentIndex, segments, cache).slice(
+      startSegmentIndex === endSegmentIndex ? startGraphemeIndex : 0,
+      endGraphemeIndex,
+    ).join('')
+  } else if (endsWithDiscretionaryHyphen) {
+    text += '-'
+  }
+
+  return text
+}
+
+function createLayoutLine(
+  prepared: InternalPreparedTextWithSegments,
+  cache: Map<number, string[]>,
+  width: number,
+  startSegmentIndex: number,
+  startGraphemeIndex: number,
+  endSegmentIndex: number,
+  endGraphemeIndex: number,
+): LayoutLine {
+  return {
+    text: buildLineTextFromRange(
+      prepared.segments,
+      prepared.kinds,
+      cache,
+      startSegmentIndex,
+      startGraphemeIndex,
+      endSegmentIndex,
+      endGraphemeIndex,
+    ),
+    width,
+    start: {
+      segmentIndex: startSegmentIndex,
+      graphemeIndex: startGraphemeIndex,
+    },
+    end: {
+      segmentIndex: endSegmentIndex,
+      graphemeIndex: endGraphemeIndex,
+    },
+  }
+}
+
+function materializeLayoutLine(
+  prepared: InternalPreparedTextWithSegments,
+  cache: Map<number, string[]>,
+  line: InternalLayoutLine,
+): LayoutLine {
+  return createLayoutLine(
+    prepared,
+    cache,
+    line.width,
+    line.startSegmentIndex,
+    line.startGraphemeIndex,
+    line.endSegmentIndex,
+    line.endGraphemeIndex,
+  )
+}
+
+function toLayoutLineRange(line: InternalLayoutLine): LayoutLineRange {
+  return {
+    width: line.width,
+    start: {
+      segmentIndex: line.startSegmentIndex,
+      graphemeIndex: line.startGraphemeIndex,
+    },
+    end: {
+      segmentIndex: line.endSegmentIndex,
+      graphemeIndex: line.endGraphemeIndex,
+    },
+  }
+}
+
+function stepLineRange(
+  prepared: InternalPreparedTextWithSegments,
+  start: LayoutCursor,
+  maxWidth: number,
+): LayoutLineRange | null {
+  const line = stepPreparedLineRange(prepared, start, maxWidth)
+  if (line === null) return null
+  return toLayoutLineRange(line)
+}
+
+function materializeLine(
+  prepared: InternalPreparedTextWithSegments,
+  line: LayoutLineRange,
+): LayoutLine {
+  return createLayoutLine(
+    prepared,
+    getLineTextCache(prepared),
+    line.width,
+    line.start.segmentIndex,
+    line.start.graphemeIndex,
+    line.end.segmentIndex,
+    line.end.graphemeIndex,
+  )
+}
+
+export function materializeLineRange(
+  prepared: PublicPreparedTextWithSegments,
+  line: LayoutLineRange,
+): LayoutLine {
+  return materializeLine(getInternalPreparedWithSegments(prepared), line)
+}
+
+// Batch low-level line geometry pass. Non-materializing counterpart to
+// layoutWithLines(), useful for shrinkwrap and other aggregate geometry work.
+export function walkLineRanges(
+  prepared: PublicPreparedTextWithSegments,
+  maxWidth: number,
+  onLine: (line: LayoutLineRange) => void,
+): number {
+  const internal = getInternalPreparedWithSegments(prepared)
+  if (internal.widths.length === 0) return 0
+
+  return walkPreparedLines(internal, maxWidth, line => {
+    onLine(toLayoutLineRange(line))
+  })
+}
+
+export function measureLineGeometry(
+  prepared: PublicPreparedTextWithSegments,
+  maxWidth: number,
+): LineGeometry {
+  return measurePreparedLineGeometry(getInternalPreparedWithSegments(prepared), maxWidth)
+}
+
+// Intrinsic-width helper for rich/userland layout work. Returns the widest
+// forced line when container width is unconstrained.
+export function measureNaturalWidth(prepared: PublicPreparedTextWithSegments): number {
+  let maxWidth = 0
+  walkLineRanges(prepared, Number.POSITIVE_INFINITY, line => {
+    if (line.width > maxWidth) maxWidth = line.width
+  })
+  return maxWidth
+}
+
+export function layoutNextLine(
+  prepared: PublicPreparedTextWithSegments,
+  start: LayoutCursor,
+  maxWidth: number,
+): LayoutLine | null {
+  const line = layoutNextLineRange(prepared, start, maxWidth)
+  if (line === null) return null
+  return materializeLineRange(prepared, line)
+}
+
+export function layoutNextLineRange(
+  prepared: PublicPreparedTextWithSegments,
+  start: LayoutCursor,
+  maxWidth: number,
+): LayoutLineRange | null {
+  return stepLineRange(getInternalPreparedWithSegments(prepared), start, maxWidth)
+}
+
+// Rich layout API for callers that want the actual line contents and widths.
+// lineHeight is optional: if omitted, read from the prepared handle's style.
+export function layoutWithLines(
+  prepared: PublicPreparedTextWithSegments,
+  maxWidth: number,
+  lineHeight?: number,
+): LayoutLinesResult {
+  const internal = getInternalPreparedWithSegments(prepared)
+  const lines: LayoutLine[] = []
+  if (internal.widths.length === 0) return { lineCount: 0, height: 0, lines }
+
+  const graphemeCache = getLineTextCache(internal)
+  const lineCount = walkPreparedLines(internal, maxWidth, line => {
+    lines.push(materializeLayoutLine(internal, graphemeCache, line))
+  })
+
+  const lh = resolveLineHeight(internal, lineHeight)
+  return { lineCount, height: lineCount * lh, lines }
+}
+
+// --- Inline-flow compatibility ---
+
+// Re-export the public PreparedTextWithSegments under the alias the inline-flow
+// module expects.  The underlying type is the same opaque branded handle.
+export type { PublicPreparedTextWithSegments as PreparedTextWithSegments }
+export type { LayoutCursor, LayoutResult, LayoutLineRange, LayoutLine }
+
+// --- Cache management ---
+
+export function clearCache(): void {
+  clearAnalysisCaches()
+  clearGraphemeSegmenter()
+  sharedLineTextCaches = new WeakMap<InternalPreparedTextWithSegments, Map<number, string[]>>()
+  clearJSCache()
+}
+
+export function setLocale(locale?: string): void {
+  setAnalysisLocale(locale)
+  clearCache()
+}