textutil

type CompositionInfo struct {
	// LineIndex is the logical-line index of the selection line.
	// Lines with index > LineIndex are "past the splice" and have
	// RenderingByteShift and RenderingYShift applied.
	LineIndex int

	// RenderingByteShift is added to a past-the-splice line's
	// committed byte offset to get its rendering byte offset. Equals
	// the composition's byte length minus the length of the committed
	// range it replaces, so it can be negative for selection-
	// replacement compositions.
	RenderingByteShift int

	// RenderingYShift is added to a past-the-splice line's committed
	// visual-Y (in pixels, top-of-line) to get its rendering visual-Y.
	// Non-zero only when WrapMode is not [WrapModeNone] and the composition
	// causes the selection line to wrap into a different number of visual
	// sub-lines.
	RenderingYShift int
}

type CompositionInfoParams struct {
	// CompositionText is the active composition's bytes — the bytes
	// inserted into the rendering text at SelectionStart, replacing
	// committed[SelectionStart:SelectionEnd].
	CompositionText string

	// LineByteOffsets is the logical-line layout of the committed text.
	LineByteOffsets *LineByteOffsets

	// SelectionStart and SelectionEnd are byte offsets into the
	// committed text describing the range the composition replaces.
	// SelectionStart == SelectionEnd for a pure insertion.
	SelectionStart int
	SelectionEnd   int

	// WrapMode toggles the visual-Y delta measurement for the
	// selection line. When [WrapModeNone], RenderingYShift in the result
	// is always 0 and the fields below are ignored.
	WrapMode WrapMode

	// CommittedSelectionLine and RenderingSelectionLine are the bytes
	// of the logical line containing the selection (SelectionStart ..
	// SelectionEnd, which always lies within a single logical line —
	// the function rejects multi-line selections), in committed and
	// rendering coordinates respectively. Required when WrapMode is
	// not [WrapModeNone]; ignored otherwise.
	CommittedSelectionLine string
	RenderingSelectionLine string

	// Face, LineHeight, LineHeightMode, TabWidth, KeepTailingSpace are
	// passed through to [MeasureLogicalLineHeight] when WrapMode is not
	// [WrapModeNone].
	Face             font.Face
	LineHeight       float64
	LineHeightMode   LineHeightMode
	TabWidth         float64
	KeepTailingSpace bool

	// CommittedFaceRuns and RenderingFaceRuns override Face for byte
	// ranges of the selection line, in committed-text and rendering-text
	// whole-text byte offsets respectively. Consulted only when WrapMode
	// is not [WrapModeNone]; nil means no overrides.
	CommittedFaceRuns []FaceRun
	RenderingFaceRuns []FaceRun

	// SelectionLineStartInBytes is the selection line's whole-text start
	// offset. The line start precedes the splice, so the offset is the
	// same in the committed and rendering texts.
	SelectionLineStartInBytes int

	// WrapWidth is the pixel width at which logical lines wrap into
	// visual sublines. Values <= 0 are treated as math.MaxInt (no
	// wrapping).
	WrapWidth int
}

type DrawOptions struct {
	Style

	// LayoutWidth is the width used to wrap and align text. When zero, the
	// drawing bounds width is used.
	LayoutWidth int

	TextColor color.Color

	DrawSelection  bool
	SelectionStart int
	SelectionEnd   int
	SelectionColor color.Color

	DrawComposition          bool
	CompositionStart         int
	CompositionEnd           int
	CompositionActiveStart   int
	CompositionActiveEnd     int
	InactiveCompositionColor color.Color
	ActiveCompositionColor   color.Color
	CompositionBorderWidth   float32

	// VisibleBounds restricts drawing to lines and glyphs that intersect this
	// rectangle. Lines fully above or below are skipped without shaping, and
	// glyphs whose drawn rectangle falls entirely outside are not submitted to
	// [(*ebiten.Image).DrawImage]. An empty rectangle draws nothing.
	VisibleBounds image.Rectangle

	// StyleRuns are paint-only style overrides applied to byte ranges of the
	// drawn string, sorted by Start and disjoint. An empty slice draws the
	// whole string uniformly.
	StyleRuns []StyleRun
}

type FaceRun struct {
	// Start is the inclusive start of the range in bytes.
	Start int

	// End is the exclusive end of the range in bytes.
	End int

	// Face measures and draws the range.
	Face font.Face
}

type HorizontalAlign int

type Insertion struct {
	// Face is the face the inserted text uses. The zero value means there is
	// no insertion.
	Face font.Face

	// IndexInBytes is the insertion's byte offset in the laid-out text.
	IndexInBytes int
}

type LineByteOffsets struct {
	// contains filtered or unexported fields
}

type LineHeightMode int

type Style struct {
	WrapMode WrapMode
	Face     font.Face

	// FaceRuns overrides Face for byte ranges of the laid-out text, sorted
	// by Start and disjoint. An empty slice measures and draws the whole
	// text with Face.
	FaceRuns []FaceRun

	// Insertion is the pending insertion point of the laid-out text. The
	// zero value means there is none.
	Insertion Insertion

	LineHeight float64

	// LineHeightMode selects how LineHeight responds to the font sizes on a
	// visual line.
	LineHeightMode LineHeightMode

	HorizontalAlign  HorizontalAlign
	VerticalAlign    VerticalAlign
	TabWidth         float64
	KeepTailingSpace bool
	EllipsisString   string
}

type StyleRun struct {
	// Start is the inclusive start of the range in bytes.
	Start int

	// End is the exclusive end of the range in bytes.
	End int

	// Color overrides the text and decoration color. Nil inherits
	// [DrawOptions.TextColor].
	Color color.Color

	// BackgroundColor fills the range's background. Nil draws no background.
	BackgroundColor color.Color

	// Underline draws a line under the text.
	Underline bool

	// Strikethrough draws a line through the text.
	Strikethrough bool
}

type TextLayoutParams struct {
	// RenderingTextRange returns rendering[start:end), where the
	// rendering text is the committed text with any active composition
	// spliced in. RenderingTextLength is the total byte length of the
	// rendering text. Required: all reads of the rendering text — both
	// the fast path and the slow-path fallback — go through this
	// callback so the caller never has to materialize the full
	// document.
	RenderingTextRange  func(start, end int) string
	RenderingTextLength int

	// Width is the rendering width.
	Width int

	// Style carries face, lineHeight, wrap mode, alignment, tab
	// width, etc. Style.FaceRuns uses rendering-text byte offsets.
	Style Style

	// CommittedTextRange returns committed[start:end). Required when
	// CompositionLen > 0; ignored otherwise.
	CommittedTextRange func(start, end int) string

	// CommittedFaceRuns carries the same face overrides as Style.FaceRuns
	// in committed-text byte offsets. Consulted only when CompositionLen
	// > 0; nil means no overrides.
	CommittedFaceRuns []FaceRun

	// PrecomputedLineByteOffsets is the logical-line layout of the committed text.
	// Optional; when nil the query falls back to an O(documentLen) walk
	// of every visual line.
	PrecomputedLineByteOffsets *LineByteOffsets

	// SelectionStart, SelectionEnd, CompositionLen describe an active
	// IME composition: bytes [SelectionStart, SelectionEnd) in the
	// committed text are replaced with bytes [SelectionStart,
	// SelectionStart+CompositionLen) in the rendering text.
	// CompositionLen == 0 means no active composition; the other
	// fields are ignored in that case.
	SelectionStart int
	SelectionEnd   int
	CompositionLen int

	// LogicalLineIndexHint / VisualLineIndexHint define the visual-line
	// coordinate system the walk starts from: the logical line at
	// LogicalLineIndexHint is treated as starting at visual-line index
	// VisualLineIndexHint, and the walk steps forward (or backward)
	// from there to the line the query resolves to. The result is
	// therefore expressed in the caller's coordinate system — (0, 0)
	// measures from line 0 (the document top); (firstLogicalLineInViewport, 0)
	// measures from the first visible line's top, used by virtualized
	// text.
	//
	// The walk is bounded by the logical-line distance between the
	// hint and the resolved line, so a caller that pins the hint inside
	// its viewport pays only O(visible) typesetting per query. The zero
	// value walks from the document top. Used only when
	// PrecomputedLineByteOffsets is set.
	LogicalLineIndexHint int
	VisualLineIndexHint  int
}

type TextPosition struct {
	X      float64
	Top    float64
	Bottom float64
}

type VerticalAlign int

type VisibleRange struct {
	// FirstLine and LastLine are the inclusive range of logical-line
	// indices the caller should draw.
	FirstLine, LastLine int

	// StartInBytes and EndInBytes are the byte range of the rendering
	// text the caller should draw: rendering[StartInBytes:EndInBytes].
	StartInBytes, EndInBytes int

	// YShift is added to the drawing-origin Y so the first sliced line
	// lands at its original screen Y. Already includes the alignment-
	// specific portion of the original Y offset, so the caller forces
	// [VerticalAlignTop] when calling [Draw].
	YShift int
}

type VisibleRangeInViewportParams struct {
	// FirstLogicalLineInViewport is the logical line whose top sits
	// at the widget-local origin (Y=0). The caller's bounds-positioning
	// places this line at the top of the rendered output, so the
	// returned VisibleRange.FirstLine is always this index (clamped to
	// the document) and YShift is always 0.
	FirstLogicalLineInViewport int

	// LineByteOffsets is the logical-line layout of the committed
	// text. The number of logical lines comes from its LineCount.
	LineByteOffsets *LineByteOffsets

	// RenderingTextRange returns rendering[start:end). The walker
	// reads each measured line through this callback so the caller
	// never has to materialize the full rendering text. Required when
	// WrapMode is not [WrapModeNone] (so the walker can shape per-line
	// content); for [WrapModeNone] only RenderingTextLength is consulted.
	RenderingTextRange func(start, end int) string

	// RenderingTextLength is the total byte length of the rendering
	// text.
	RenderingTextLength int

	// ViewportSize describes the rendering box the walker operates
	// against: X is the wrap width passed through to
	// [VisualLineCountForLogicalLine] when WrapMode is not
	// [WrapModeNone], and Y is the distance below
	// FirstLogicalLineInViewport's top that the visible region extends
	// downward. The walk stops once cumulative line heights exceed Y,
	// leaving one line of slack so the caller's inner Y clip can handle
	// off-by-one rounding.
	ViewportSize image.Point

	// Face, LineHeight, LineHeightMode, TabWidth, KeepTailingSpace are
	// passed through to [VisualLineCountForLogicalLine] when WrapMode is
	// not [WrapModeNone].
	Face             font.Face
	LineHeight       float64
	LineHeightMode   LineHeightMode
	TabWidth         float64
	KeepTailingSpace bool

	// FaceRuns are the per-range face overrides of the rendering text,
	// sorted by Start and disjoint.
	FaceRuns []FaceRun

	// Insertion is the pending insertion point of the rendering text. The
	// zero value means there is none.
	Insertion Insertion

	// WrapMode toggles between a per-line shaping walk (any wrapping
	// mode) and a flat LineHeight*idx arithmetic ([WrapModeNone]).
	WrapMode WrapMode

	// Composition is the splice info from [ComputeCompositionInfo].
	// The zero value means "no active composition".
	Composition CompositionInfo
}

type WrapMode int