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 AutoWrap is on 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

	// AutoWrap toggles the visual-Y delta measurement for the
	// selection line. When false, RenderingYShift in the result is
	// always 0 and the fields below are ignored.
	AutoWrap bool

	// 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 AutoWrap is
	// true; ignored otherwise.
	CommittedSelectionLine string
	RenderingSelectionLine string

	// Face, LineHeight, TabWidth, KeepTailingSpace are passed through
	// to [MeasureLogicalLineHeight] when AutoWrap is true.
	Face             text.Face
	LineHeight       float64
	TabWidth         float64
	KeepTailingSpace bool

	// 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 {
	Options

	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, when non-empty, restricts per-line drawing to lines that
	// intersect this rectangle. Lines fully above or below are skipped without
	// shaping, which matters for very long text whose [bounds] greatly exceed
	// the on-screen viewport. When empty, [bounds] is used (back-compatible).
	VisibleBounds image.Rectangle
}

type HorizontalAlign int

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

type Options struct {
	AutoWrap         bool
	Face             text.Face
	LineHeight       float64
	HorizontalAlign  HorizontalAlign
	VerticalAlign    VerticalAlign
	TabWidth         float64
	KeepTailingSpace bool
	EllipsisString   string
}

type TextIndexFromPositionParams struct {
	// Position is the (x, y) point in the rendering plane to query.
	// Y is measured from the top of the rendered text.
	Position image.Point

	// 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

	// Options carries face, lineHeight, autoWrap, alignment, tab
	// width, etc.
	Options *Options

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

	// LineByteOffsets is the logical-line layout of the committed text.
	// Optional; when nil [TextIndexFromPosition] falls back to an
	// O(documentLen) walk of every visual line.
	LineByteOffsets *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 are an optional hint
	// that tells [TextIndexFromPosition] where to start its per-
	// logical-line walk instead of starting from line 0.
	// LogicalLineIndexHint is a logical-line index in committed text;
	// VisualLineIndexHint is the cumulative number of visual lines
	// preceding that logical line in committed text. The walk steps
	// forward (or backward) from the hint measuring one logical line
	// at a time, so a caller that places the hint inside its viewport
	// pays O(visible lines) of typesetting per query instead of
	// walking from the document top.
	//
	// Both fields are optional. The zero value means "start from line
	// 0," equivalent to walking from the top of the document — correct
	// but O(documentLen) when the click is far down. Used only when
	// LineByteOffsets is set.
	LogicalLineIndexHint int
	VisualLineIndexHint  int
}

type TextPosition struct {
	X      float64
	Top    float64
	Bottom float64
}

type TextPositionFromIndexParams struct {
	// Index is the byte offset in the rendering text to query.
	Index int

	// 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

	// Options carries face, lineHeight, autoWrap, alignment, tab
	// width, etc.
	Options *Options

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

	// LineByteOffsets is the logical-line layout of the committed text.
	// Optional; when nil [TextPositionFromIndex] falls back to an
	// O(documentLen) walk of every visual line.
	LineByteOffsets *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 pin the result's Y
	// coordinate system: the function treats the logical line at
	// LogicalLineIndexHint as starting at visual-line index
	// VisualLineIndexHint, and walks forward (or backward) from there
	// to whichever line contains Index. The returned position's Top
	// is therefore measured in the caller's coordinate system —
	// (0, 0) means "Y is measured from line 0," matching the legacy
	// behavior; (firstLogicalLineInViewport, 0) means "Y is measured
	// 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 line containing Index, so a caller that pins the
	// hint inside its viewport pays only O(visible) typesetting per
	// query. Used only when LineByteOffsets is set and Options.AutoWrap
	// is true.
	LogicalLineIndexHint int
	VisualLineIndexHint  int
}

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
	// AutoWrap is true (so the walker can shape per-line content); for
	// AutoWrap=false 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 AutoWrap is true, 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, TabWidth, KeepTailingSpace are passed through
	// to [VisualLineCountForLogicalLine] when AutoWrap is true.
	Face             text.Face
	LineHeight       float64
	TabWidth         float64
	KeepTailingSpace bool

	// AutoWrap toggles between a per-line shaping walk (true) and a
	// flat LineHeight*idx arithmetic (false).
	AutoWrap bool

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