cell.go

// SPDX-FileCopyrightText: Copyright 2026 Carabiner Systems, Inc
// SPDX-License-Identifier: Apache-2.0

package termtable

import "io"

// Padding controls the empty space reserved inside a cell around its
// content. Values are measured in terminal columns (left/right) and rows
// (top/bottom).
type Padding struct {
	Left, Right, Top, Bottom int
}

// DefaultPadding is the padding applied table-wide when
// WithTablePadding is not supplied: one column of left/right
// breathing room, no vertical padding.
func DefaultPadding() Padding {
	return Padding{Left: 1, Right: 1, Top: 0, Bottom: 0}
}

// Cell is the fundamental content-bearing element. Cells belong to at
// most one row and occupy a rectangle in the table's grid defined by
// their anchor (GridRow, GridCol) and span (ColSpan, RowSpan).
type Cell struct {
	id string

	// table is the owning table, set when the cell is attached to a
	// row. Retained so Cell methods can resolve cross-section
	// information (e.g., absolute grid row).
	table *Table

	// Content source: at most one of content / reader is set. If
	// hasContent is true, content holds the authored string. Otherwise,
	// reader (if non-nil) is consumed by Measure on its first visit;
	// the resulting bytes are cached back into content and hasContent
	// is flipped so subsequent renders reuse the buffered data.
	content    string
	hasContent bool
	reader     io.Reader
	resolved   bool
	resolveErr error

	// contentSourceSwapped is set when WithContent replaced an
	// existing reader (or vice versa). The flag is consumed on
	// attachCell, which emits a ContentSourceReplacedEvent warning
	// against the owning Table.
	contentSourceSwapped bool

	colSpan int
	rowSpan int

	section    sectionKind
	sectionRow int
	gridCol    int

	// style is the cell's local style. It is merged over the row's,
	// column's, and table's styles to produce the effective style
	// for rendering. nil means "inherit everything".
	style *Style

	// adopted is set once the cell belongs to a row.
	adopted bool
}

// NewCell constructs a detached cell with the given options. A detached
// cell has no grid position until it is passed to a row via WithCell or
// Row.AttachCell.
func NewCell(opts ...CellOption) *Cell {
	c := &Cell{
		colSpan: 1,
		rowSpan: 1,
	}
	for _, o := range opts {
		o(c)
	}
	return c
}

// ID returns the cell's user-assigned ID, or the empty string.
func (c *Cell) ID() string { return c.id }

// ColSpan returns the number of columns the cell occupies.
func (c *Cell) ColSpan() int { return c.colSpan }

// RowSpan returns the number of rows the cell occupies within its
// section.
func (c *Cell) RowSpan() int { return c.rowSpan }

// GridRow returns the absolute grid row of the cell's anchor across
// the whole table (headers first, then body, then footers). For
// detached cells (constructed with NewCell but never attached to a
// row), returns the section-local row since no table context exists.
func (c *Cell) GridRow() int {
	if c.table == nil {
		return c.sectionRow
	}
	return absRowOf(c.table, c)
}

// GridCol returns the zero-based column of the cell's anchor.
func (c *Cell) GridCol() int { return c.gridCol }

// Align returns the cell's horizontal alignment. Reads the cell's
// style; returns AlignLeft when no alignment has been set at the cell
// level (column, row, and table cascade happens at render time).
func (c *Cell) Align() Alignment {
	if c.style != nil && c.style.set&sAlign != 0 {
		return c.style.align
	}
	return AlignLeft
}

// Content returns the cell's authored string content. If the cell was
// configured with WithReader and the reader has not yet been consumed,
// the empty string is returned.
func (c *Cell) Content() string { return c.content }

func (c *Cell) elementID() string { return c.id }