//
//  DTCoreTextLayoutFrame.h
//  WeRead
//
//  Reverse-engineered from binary analysis
//  Based on DTCoreText open-source library, customized by WeRead
//
//  DTCoreText is an open-source library for rendering HTML with CoreText.
//  This class represents a single frame of laid-out text.
//

#import <Foundation/Foundation.h>
#import <CoreText/CoreText.h>

@class DTCoreTextLayoutLine;
@class DTCoreTextGlyphRun;
@class NSAttributedString;

NS_ASSUME_NONNULL_BEGIN

/**
 * DTCoreTextLayoutFrame - Represents a single frame of laid-out text.
 *
 * This class wraps CTFrame and provides high-level access to the
 * layout of text. It contains an array of DTCoreTextLayoutLine objects
 * and provides methods for drawing, hit testing, and accessing layout information.
 *
 * Key features:
 * - Wraps CTFrame for high-level access
 * - Contains array of DTCoreTextLayoutLine objects
 * - Supports drawing to CGContext
 * - Provides hit testing for text selection
 * - Handles complex text layout with multiple columns
 */
@interface DTCoreTextLayoutFrame : NSObject

#pragma mark - Properties

/** The attributed string that was laid out */
@property (nonatomic, strong, readonly) NSAttributedString *attributedString;

/** The range of the attributed string represented by this frame */
@property (nonatomic, assign, readonly) NSRange range;

/** The bounding rectangle for this frame */
@property (nonatomic, assign, readonly) CGRect frame;

/** The CTFrame reference */
@property (nonatomic, assign, readonly) CTFrameRef ctFrame;

/** Array of DTCoreTextLayoutLine objects */
@property (nonatomic, strong, readonly) NSArray<DTCoreTextLayoutLine *> *lines;

/** Number of lines in this frame */
@property (nonatomic, assign, readonly) NSUInteger numberOfLines;

/** The rendered content height */
@property (nonatomic, assign, readonly) CGFloat contentHeight;

/** The maximum Y coordinate of the content */
@property (nonatomic, assign, readonly) CGFloat maximumY;

/** The minimum Y coordinate of the content */
@property (nonatomic, assign, readonly) CGFloat minimumY;

/** Array of glyph runs in this frame */
@property (nonatomic, strong, readonly) NSArray<DTCoreTextGlyphRun *> *glyphRuns;

/** Whether the frame needs layout */
@property (nonatomic, assign) BOOL needsLayout;

/** The layout size used for this frame */
@property (nonatomic, assign) CGSize layoutSize;

/** The string index where layout ended */
@property (nonatomic, assign, readonly) NSUInteger stringIndex;

/** The visible string range (after truncation) */
@property (nonatomic, assign, readonly) NSRange visibleStringRange;

#pragma mark - Initialization

/**
 * Initialize with attributed string, range, and CTFrame.
 *
 * @param attributedString The attributed string
 * @param range The string range
 * @param ctFrame The CoreText frame
 * @return Initialized layout frame
 */
- (instancetype)initWithAttributedString:(NSAttributedString *)attributedString
                                   range:(NSRange)range
                                ctFrame:(CTFrameRef)ctFrame;

#pragma mark - Line Access

/**
 * Returns the array of layout lines.
 *
 * @return Array of DTCoreTextLayoutLine objects
 */
- (NSArray<DTCoreTextLayoutLine *> *)lines;

/**
 * Returns the line at the specified index.
 *
 * @param index The line index
 * @return The layout line at the index, or nil
 */
- (nullable DTCoreTextLayoutLine *)lineAtIndex:(NSUInteger)index;

/**
 * Returns the line that contains the given string index.
 *
 * @param index The string index
 * @return The layout line containing the index, or nil
 */
- (nullable DTCoreTextLayoutLine *)lineContainingStringIndex:(NSUInteger)index;

/**
 * Returns the index of the line containing the given point.
 *
 * @param point The point to test
 * @return The line index, or NSNotFound
 */
- (NSUInteger)lineIndexContainingPoint:(CGPoint)point;

#pragma mark - Drawing

/**
 * Draw the layout frame content into a CGContext.
 *
 * @param context The CGContext to draw into
 */
- (void)drawInContext:(CGContextRef)context;

/**
 * Draw the layout frame with a specific options dictionary.
 *
 * @param context The CGContext to draw into
 * @param options Drawing options
 */
- (void)drawInContext:(CGContextRef)context options:(nullable NSDictionary *)options;

#pragma mark - Hit Testing

/**
 * Returns the string index at the given point.
 *
 * @param point The point to test
 * @return The string index, or NSNotFound
 */
- (NSUInteger)stringIndexAtPoint:(CGPoint)point;

/**
 * Returns the rect for the given string index.
 *
 * @param index The string index
 * @return The rect for the character
 */
- (CGRect)rectForStringIndex:(NSUInteger)index;

/**
 * Returns the cursor position for a given string index.
 *
 * @param index The string index
 * @return The cursor rect
 */
- (CGRect)cursorRectForIndex:(NSUInteger)index;

#pragma mark - Text Geometry

/**
 * Returns the baseline origin for a given string index.
 *
 * @param index The string index
 * @return The baseline origin point
 */
- (CGPoint)baselineOriginForStringIndex:(NSUInteger)index;

/**
 * Returns the frame for a given string range.
 *
 * @param range The string range
 * @return The bounding rect for the range
 */
- (CGRect)frameForStringRange:(NSRange)range;

/**
 * Returns the string range for a given rect.
 *
 * @param rect The rect to test
 * @return The string range within the rect
 */
- (NSRange)stringRangeForRect:(CGRect)rect;

#pragma mark - Line Geometry

/**
 * Returns the line origins.
 *
 * @return Array of CGPoint values wrapped in NSValue
 */
- (NSArray<NSValue *> *)lineOrigins;

/**
 * Returns the line frames.
 *
 * @return Array of CGRect values wrapped in NSValue
 */
- (NSArray<NSValue *> *)lineFrames;

#pragma mark - Truncation

/**
 * Returns whether the frame is truncated.
 */
- (BOOL)isTruncated;

/**
 * Returns the truncation string range.
 */
- (NSRange)truncatedStringRange;

#pragma mark - Layout Updates

/**
 * Invalidates the layout, forcing recalculation on next access.
 */
- (void)invalidateLayout;

/**
 * Forces a layout pass.
 */
- (void)layoutIfNeeded;

@end

NS_ASSUME_NONNULL_END