tree

type Column struct {
	// Header is the column title. A tree whose columns are all untitled shows
	// no header row at all — a one-column outline with a header bar over it
	// reads as a table that forgot its other columns.
	Header string
	// Width is the column's width in points; 0 takes a default. It is a floor
	// as well as a starting point — the column grows to fit wider content and
	// to a drag, but never shrinks below it. See pushColumns for the etable
	// sizing pass that makes the floor necessary rather than merely tidy.
	Width float32
	// Resizable lets the user drag this column's right edge.
	Resizable bool
	// Cell draws the column's content for one row, inside a padded cell Ui.
	// On [Input.Outline] it replaces the plain label and runs after the indent
	// and the disclosure control, so a host can put a badge, a count or a
	// secondary tint on the label without giving up the outline chrome.
	//
	// A nil Cell on a host column emits nothing for that column; a nil Cell on
	// the outline draws the node's [Tree.Labels] entry.
	//
	// It takes the whole [Row] rather than the node, because a cell that
	// varies on expansion — a count of what a closed section hides, an indent
	// guide, a different glyph on a leaf — otherwise has to reach back into
	// the [State] it passed in, during the widget's own render pass, to ask
	// something the renderer is already holding.
	//
	// # Three things about this that bite
	//
	// Interactive widgets are allowed and win the pointer over the row's own
	// click sense — that is the arbitration in this file's header comment, and
	// it means a per-row control works, at the price of that control's rect no
	// longer selecting the row. Plain labels must be emitted Selectable(false)
	// or they swallow the row click; the default label does.
	//
	// And a TRUNCATING label takes the whole width it is offered, so anything
	// emitted after it in the same cell is pushed out of view. A count, a
	// chip or a glyph that has to survive a long label belongs in a column of
	// its own, whose width is reserved before the label is laid out — not
	// after the label in this one.
	//
	// The third is a HEIGHT BUDGET, and it is the one with no diagnostic.
	// Content is centred on the row by egui_table's own cell layout, but only
	// while it fits [Input.RowHeight]: something taller is pushed down to the
	// row's top edge and hangs off the bottom, under the next row and through
	// the selection outline, silently (see paddedCell for the egui clamp that
	// does it). At the 22-point default a line of body text fits and a DEFAULT
	// Button does not — a button is its text plus button_padding.y twice. A
	// per-row control therefore wants `.Small()`, which drops that padding and
	// the interact_size floor with it, the way disclose draws the disclosure
	// control. A host that wants full-size controls in its rows should raise
	// [Input.RowHeight] instead.
	Cell func(r Row)
}

type Input struct {
	// Ids is the host's widget id stack. Render opens its own IdScope under
	// it, so two trees in one frame need only differ in ScopeKey.
	Ids *c.WidgetIdStack
	// ScopeKey names this tree within the host's id space; empty uses "tree".
	// Two trees sharing a host and a ScopeKey share widget ids, which shows up
	// as one of them never seeing a click.
	ScopeKey string
	// Tree is the hierarchy. Validated every frame — the flatten refuses a
	// broken one rather than drawing a plausible outline with arbitrary
	// subtrees missing.
	Tree Tree
	// State is the host-owned expansion, selection and cursor. Required: a
	// tree with nowhere to record what is open cannot be drawn. Render binds
	// it to Tree before reading anything out of it, so it survives a rebuild
	// exactly as far as [Tree.Keys] lets it.
	State *State

	// Outline configures the first column — the one carrying the indent, the
	// disclosure control and the label. Its Cell overrides the label.
	Outline Column
	// Columns are the host's own columns, drawn to the right of the outline.
	Columns []Column

	// RowHeight is the fixed height of every row; 0 takes defaultRowHeight.
	RowHeight float32
	// MaxHeight caps the vertical extent the table claims. Feed it the pane's
	// measured height, from c.CapturePaneSize, with a constant to fall back on
	// for the first frame — the probe answers one frame late and not at all on
	// the first. That is what every in-repo adopter does.
	//
	// Left at 0 the table falls back to endETable's auto-fit heuristic, capped
	// by ETABLE_AUTOFIT_CAP_PX, which a tree of any length overruns. That is
	// only the right answer in a host that already bounds the tree tightly and
	// knows it stays short.
	MaxHeight float32
	// Indent is the horizontal step per depth level; 0 takes defaultIndent.
	Indent float32
	// Striped tints odd rows. Off by default: an indent already gives the eye
	// a per-row landmark, and a zebra competes with the selection fill for the
	// same signal. The stripe is painted by the row block, not by etable's own
	// Striped — etable paints its zebra in cell_ui, which runs after the row
	// block and would cover it.
	Striped bool

	// WidthEpoch, when non-zero, is handed to the table as its apply
	// generation (ADR-0151): the binding writes the column widths into the
	// crate's state only when it changes, so a host that resolves widths from
	// stored overrides bumps it when they change and leaves the reader's live
	// drag alone in between. Zero keeps the crate's own state, as before.
	WidthEpoch uint32
	// MinColumnWidth, when positive, is the drag floor for every column in
	// place of each column's seed width; MaxColumnWidth, when positive, the
	// ceiling. A host persisting widths passes the bounds it stores, so a
	// column cannot be dragged below what will come back on the next load.
	MinColumnWidth float32
	MaxColumnWidth float32
}

type Result struct {
	// Rows is the row sequence drawn this frame, borrowed from the State's
	// scratch: valid until the next Render on that State, and not to be
	// retained. Useful for "how many rows are showing" and for mapping a node
	// to its row without a second flatten.
	Rows []Row
	// Clicked is the node whose row was clicked. The selection has already
	// been updated for it, honouring ctrl (toggle) and shift (extend from the
	// cursor).
	Clicked int32
	// Activated is the node whose row was double-clicked — "open this", by the
	// convention every file manager uses. An interior node is also toggled;
	// the host decides what a leaf activation means.
	Activated int32
	// Toggled is the node whose expansion changed, whether from its disclosure
	// control or from a double-click.
	Toggled int32
	// Err is the flatten's, on a structurally broken Tree. The widget draws
	// the message in place of the outline rather than drawing nothing, because
	// the failures it reports — a dangling parent index, a cycle — are
	// programming errors in the host and silence makes them look like an empty
	// result set.
	Err error
	// Widths is what the table reported its columns to be, outline column
	// first, when last frame's report was available; nil otherwise. A host
	// persisting widths feeds it to its resolver (ADR-0151).
	Widths []float32
}

type Row struct {
	// Node indexes [Tree.Labels].
	Node int32
	// Depth is 0 for a root and one more than its parent's otherwise. It is
	// the indent level, not a pixel count — the renderer multiplies.
	Depth int32
	// HasChildren is whether this node has any children at all, which is what
	// decides if a disclosure control is drawn. It is independent of Expanded:
	// a collapsed interior node has children and shows a closed control.
	HasChildren bool
	// Expanded is whether this node's children follow it in the row sequence.
	// Always false for a leaf.
	Expanded bool
	// IsLastChild is whether this node is the final one among its siblings —
	// including at depth 0, where the siblings are the roots.
	//
	// Carried from M1 although nothing reads it yet: it is exactly what indent
	// guides need (the vertical line from a parent stops at its last child),
	// and ADR-0176 SD9 defers the guides rather than the field, so adding them
	// later needs no change here or in any caller.
	IsLastChild bool
}

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

type Tree struct {
	// Labels is what the renderer draws for each node.
	Labels []string
	// Parents indexes each node's parent, or -1 for a root. Several roots are
	// allowed and are laid out one after another at depth 0 — a forest is the
	// natural shape of a schema's tables or a filesystem's mount points, and
	// inventing a virtual root would state a containment nothing in the data
	// supports.
	//
	// No ordering is required: a parent may appear after its child. Siblings
	// are drawn in the order they appear here.
	Parents []int32
	// Keys optionally identifies each node across rebuilds, and is what lets a
	// [State] outlive one. Leave it nil and the State files everything under
	// node indices, which are stable only as long as the host's ordering is —
	// for a host that filters or re-parses, one keystroke.
	//
	// A key is the host's own name for the thing the row shows: a section id,
	// a category name, an index path, a slug. It has to be unique, because it
	// IS the identity — two nodes sharing a key share one expansion entry and
	// one selection entry, and read as one node to everything in State. That
	// is not checked: the check is a map build of every key on every frame,
	// which is a per-frame cost for a host bug that shows up the first time
	// the two rows are opened.
	//
	// When present it must have one entry per node; [Tree.Validate] rejects a
	// short or long column rather than filing part of the tree by key and the
	// rest by index.
	Keys []string
}