kit

type Bar struct {
	Label string
	Value float64
	Text  string
}

type BarChart struct {
	Theme   Theme
	Glyphs  Glyphs
	Bars    []Bar
	Maximum float64
}

type Border struct {
	Top, Bottom, Left, Right string
	TopLeft, TopRight        string
	BottomLeft, BottomRight  string
}

type Box struct {
	// Theme is the look. A box's parts each have a fixed role in one — the frame is
	// a border, the interior is a surface, the title is a heading — so there is
	// nothing here for a caller to choose between and no style of its own to set.
	Theme Theme
	// Glyphs are the characters the frame is drawn with, which is a fact about the
	// terminal rather than about the look: a box drawn with line characters on a
	// terminal that cannot show them is a box drawn in mojibake.
	Glyphs Glyphs
	// Border is which frame to draw. The zero value takes the rounded one from the
	// glyph set, which reads as a panel; [Box.Bare] draws none.
	Border Border
	// Padding is held clear inside the border.
	Padding layout.Inset
	// Bare draws no frame at all, for a box that only pads and fills.
	Bare bool
	// Title sits in the top border, indented one column so the corner reads as a
	// corner.
	Title      string
	TitleAlign layout.Align
	// Footer sits in the bottom border, on the same terms as the title.
	Footer      string
	FooterAlign layout.Align
}

type Cell struct {
	Preferred int
	// Paint runs during drawing and must only paint its view; it must not mutate
	// application state, publish output, or start work.
	Paint func(view grid.View, base grid.Style)
}

type Code struct {
	// Gutter draws beside the source. Nil gives every column to the code.
	Gutter headless.RowGutter
	// contains filtered or unexported fields
}

type Column struct {
	Title string
	Align layout.Align
	// Size is how the shared layout allocator sizes this column. Use layout.Fixed
	// for an exact width, layout.Flex for a share of what remains, and
	// layout.Measured to fit the widest title or cell. The zero value defaults to
	// layout.Flex(1), so an unsized column participates in the remaining space.
	Size layout.Sizing
}

type Composer struct {
	Theme Theme
	// Prompt marks the first row of the field. Empty draws no marker and gives the
	// columns back to the text.
	Prompt string
	// Hints are the actions drawn under the field, in the order they matter. An action
	// with nothing bound to it is not shown, so an empty row costs nothing to ask for.
	// Bindings come from [Composer.Editor], keeping input and the hint row on one map.
	Hints []keymap.Action
	// MaxRows caps how tall the field grows before it scrolls. Zero uses
	// [DefaultComposerRows].
	MaxRows int
	// contains filtered or unexported fields
}

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

type DialogConfig struct {
	// Stack owns modal ordering and is required.
	Stack *headless.Stack
	// Open is optional caller-owned state. Nil starts locally closed.
	Open headless.Accessor[bool]
	// Theme and Glyphs define the panel appearance.
	Theme  Theme
	Glyphs Glyphs
	// Title and Description are copied semantic text; Title also labels the border.
	Title       string
	Description string
	// Body is the optional live content inside the panel.
	Body headless.Widget
	// Where places the panel, and Border selects its frame style.
	Where  layout.Placement
	Border Border
	// Keys supplies the map used to draw Hints. Hints is copied.
	Keys  *keymap.Map
	Hints []keymap.Action
}

type DialogPanel struct {
	Theme Theme
	// Where the dialog goes. The zero value centres it and fills what the margin
	// leaves, which is what a dialog with a lot in it wants.
	Where layout.Placement
	// Glyphs are the characters the frame is drawn with. See [Box.Glyphs].
	Glyphs Glyphs
	// Border draws the frame. The zero value takes the rounded one from the glyph
	// set, which reads as a panel.
	Border Border
	// Keys is where the hints' keystrokes are read from, and Hints are the actions to
	// show along the bottom border, where they do not cost a row. An action with
	// nothing bound to it is not shown.
	Keys  *keymap.Map
	Hints []keymap.Action
	// contains filtered or unexported fields
}

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

type DiffConfig struct {
	Theme   Theme
	Glyphs  Glyphs
	Hunks   []diff.Hunk
	Numbers bool
}

type Entry struct {
	Theme Theme
	// Label names the source or role of the body. Empty draws no label and no gutter.
	Label string
	// LabelStyle overlays Theme.Muted. The zero value keeps the ordinary receding
	// label; a caller that gives a product role visual emphasis supplies that role's
	// style explicitly.
	LabelStyle grid.Style
	// Body is the text. Newlines are line breaks; everything else wraps.
	Body string
	// Trailing is how many blank rows follow, so consecutive entries do not run
	// together. Zero uses one, which is what separates without doubling the spacing.
	Trailing int
	// contains filtered or unexported fields
}

type Form struct {

	// Theme is the look, and Glyphs the characters the marks beside a choice are drawn
	// with.
	Theme  Theme
	Glyphs Glyphs
	// Title sits above the fields. Empty draws none and costs no row.
	Title string
	// Hints are the controller actions to show under the fields. Their keystrokes
	// always come from the controller's own map, so help cannot disagree with input.
	// An action with nothing bound to it is not shown.
	Hints []keymap.Action
	// contains filtered or unexported fields
}

type FormConfig struct {
	// Theme and Glyphs define field roles and choice marks.
	Theme  Theme
	Glyphs Glyphs
	// Controller owns fields, keys, validation and submission and is required.
	Controller *headless.Form
	// Title is copied. Empty omits the heading row.
	Title string
	// Hints is copied and resolved through Controller.Keys.
	Hints []keymap.Action
}

type Glyphs struct {
	// The lines a box is drawn with, rounded and square.
	Horizontal, Vertical                       string
	TopLeft, TopRight, BottomLeft, BottomRight string
	RoundTopLeft, RoundTopRight                string
	RoundBottomLeft, RoundBottomRight          string

	// Ellipsis stands for text that did not fit.
	Ellipsis string
	// Bullet marks an item in a list, and Marker the one under the cursor.
	Bullet, Marker string
	// Taken and Free are the two states of a choice: one that has been made, and one
	// that is still on offer. They are a pair and are drawn in the same column, so
	// they have to be the same width or the labels beside them do not line up.
	Taken, Free string
	// ScrollTrack and ScrollThumb are the two halves of a scrollbar.
	ScrollTrack, ScrollThumb string
	// SliderTrack is the line a bounded value moves over and SliderThumb is its current
	// position. They are separate from a scrollbar because one is a control and the
	// other reports a viewport.
	SliderTrack, SliderThumb string
	// BarFull and BarEmpty are the two halves of a progress bar, and BarSteps are the
	// pieces of a cell it is part way through — from the narrowest to the widest, in
	// order, with as many of them as the set has. A set with none draws the last cell
	// whole or not at all, which is what an eight-step bar degrades to and not a
	// separate design.
	BarFull, BarEmpty string
	BarSteps          []string
	// Sparkline is the ordered set of sample heights, from lowest to highest.
	Sparkline []string
	// Expanded and Collapsed are the two states of a branch in a tree: one showing
	// what is under it, and one inviting the reader to look. Like Taken and Free they
	// are drawn in the same column and have to be the same width.
	Expanded, Collapsed string
	// Ascending and Descending mark the column a table is sorted by.
	Ascending, Descending string
	// Spinner is the frames of a busy indicator, in order.
	Spinner []string
}

type Help struct {
	// Theme is the look. Each part of a hint has a fixed role in one — the key is
	// the thing to press, what it does is a note about it — so there is nothing here
	// to choose between.
	Theme Theme
	// Keys is where the keystrokes come from.
	Keys *keymap.Map
	// Show are the actions to show, in the order they matter. Hiding one is leaving it
	// out: an action that works and that nobody needs told about is simply not listed.
	//
	// Each identifier is shown as words by this appearance layer; the key map carries
	// only identity and binding policy.
	Show []keymap.Action
	// Separator sits between hints. Empty uses two spaces, which separates without
	// adding another thing to look at.
	Separator string
}

type Image struct {
	// Of is the picture, as the terminal knows it. The zero value is no picture,
	// which draws the alternative text.
	Of graphics.Image
	// Cell is how many pixels one terminal cell is, as reported by the host.
	// The zero value is a terminal that never said, which draws the alternative text:
	// a picture scaled by an invented cell size is a picture the wrong shape.
	Cell image.Point
	// MaxRows caps how tall the picture may be, so one from somewhere else cannot
	// take the whole screen. Zero is a cap of eight rows, which is about a third of a
	// terminal and small enough to read around.
	MaxRows int

	// Alt is what to say where the picture cannot be shown.
	Alt string
	// Align is where a picture narrower than its space sits.
	Align layout.Align
	// Theme is the look of the alternative text, which is text present for reference
	// rather than for reading.
	Theme Theme
}

type Label struct {
	Text  string
	Style grid.Style
	Align layout.Align
	// Ellipsis marks a truncation. Empty means truncate silently, which is right for
	// a value the user can see in full elsewhere and wrong for prose.
	Ellipsis string
}

type LineNumbers struct {
	Style grid.Style
	// First is the number of source line one. Zero uses one, which is how a whole
	// document is numbered; a snippet beginning later sets the actual first line.
	First int
	// Separator is drawn after the number column. Empty draws none.
	Separator string
	// Gap is the clear space after Separator. Zero uses one column.
	Gap int
}

type LinkConfig struct {
	Enabled bool
	Exists  func(path string) bool
}

type Overlay struct {
	layout.Placement
	// Theme is the look, of which an overlay uses exactly one part: the scrim it
	// paints over what it covers, so the eye goes to the layer and it is obvious that
	// what is behind is not the thing to act on. A zero theme covers nothing.
	Theme Theme
}

type Palette struct {
	// Found is what to show, best first, as the registry ranked it.
	Found []headless.Found
	// Selected is the index under the cursor.
	Selected int

	// Theme is the look. Every part of a row has a fixed role in one — a name is
	// text, the row under the cursor is the selection, a matched letter is the accent
	// — so there is nothing here to choose between.
	Theme Theme
	// Glyphs are the characters the marker is drawn with, which is a fact about the
	// terminal rather than about the look.
	Glyphs Glyphs
	// Empty is what to say when nothing matched. Empty says so in words, because a
	// blank space reads as a bug rather than as an answer.
	Empty string
}

type Panel struct {

	// Box is the panel's frame, fill, padding, title, and footer. Replacing it changes
	// appearance and interior geometry, never the child's behavior.
	Box Box
	// contains filtered or unexported fields
}

type PanelConfig struct {
	Box     Box
	Content headless.Focusable
}

type Paragraph struct {

	// Indent is held clear on the left of every row, including continuations, so a
	// wrapped paragraph reads as one block rather than as several.
	Indent int
	// MaxRows caps the height. Zero means no cap; a cap replaces the last row it
	// keeps with one ending in an ellipsis.
	MaxRows int
	// contains filtered or unexported fields
}

type Printer interface {
	// Print draws content into the terminal's own output, above the interface, where
	// it stays after the program exits.
	Print(content grid.Drawable)
}

type Progress struct {
	// Theme is the look: the bar is the thing the interface is about, its track is
	// structure to skip, and the numbers beside it are for reference.
	Theme Theme
	// Glyphs are what the bar is drawn with. A progress bar is furniture, so one
	// given no glyphs draws nothing — see the package documentation.
	Glyphs Glyphs

	// Done and Total are the work: how much of it is finished, and how much there is
	// altogether. A total of zero draws an empty bar rather than a full one, which is
	// the honest reading of "nothing to do yet".
	Done, Total int
	// Label goes before the bar, truncated to fit. It is what the work is, and it
	// belongs here rather than above because a bar with no name is a bar nobody can
	// act on when two of them are on screen.
	Label string
	// Percent writes the fraction after the bar as a number. The field is omitted
	// when it cannot fit in full; clipping a percentage could display another,
	// plausible percentage.
	Percent bool
}

type Scrim struct {
	// Color is what the sheet is made of, and Opacity how much of it shows, from 0
	// for nothing to 1 for paint.
	Color   grid.Color
	Opacity float64
}

type Scrollbar struct {
	// Total is how many rows of content there are, Window how many are shown, and
	// Offset how many are above the window.
	Total, Window, Offset int
	// Theme is the look: the track is structure the eye should skip, and the thumb
	// is where you are.
	Theme Theme
	// Glyphs supplies the track and thumb. A zero set draws nothing, following the
	// same coverage rule as every other piece of kit furniture.
	Glyphs Glyphs
}

type Settings[T any] struct {
	Theme Theme
	// Label and Value are the two columns shown for an item. Nil returns an empty
	// column. Both run during measurement and drawing and must be observationally
	// pure; Change is the event-side mutation boundary.
	Label func(T) string
	Value func(T) string
	// ValueWidth caps the fitted value column. Zero leaves it uncapped.
	ValueWidth int
	// contains filtered or unexported fields
}

type SettingsConfig[T any] struct {
	// Theme defines row and value appearance.
	Theme Theme
	// Items are copied into the constructed controller.
	Items []T
	// Label and Value project the two visible columns. Nil produces an empty column.
	// They run during measurement and drawing and must be observationally pure.
	Label func(T) string
	Value func(T) string
	// Change applies a value action. Nil makes values read-only.
	Change func(index int, item T, action keymap.Action) bool
	// Keys browse rows; EditKeys change the selected value. Nil uses the respective defaults.
	Keys     *keymap.Map
	EditKeys *keymap.Map
	// Wrap moves row selection across the ends.
	Wrap bool
	// ValueWidth caps the right column. Zero leaves it uncapped.
	ValueWidth int
}

type Slider struct {
	// Theme and Glyphs choose the appearance of the track and thumb.
	Theme  Theme
	Glyphs Glyphs
	// Format turns the integer value into its right-hand label. Nil uses strconv.Itoa;
	// returning an empty string omits the value and leaves that room to the track. A
	// non-empty value is likewise omitted when it cannot fit in full, because clipped
	// digits can read as another value. Format runs during drawing and must be an
	// observationally pure projection.
	Format func(int) string
	// contains filtered or unexported fields
}

type SliderConfig struct {
	// Theme and Glyphs define the track appearance.
	Theme  Theme
	Glyphs Glyphs
	// Value is optional caller-owned state. Nil starts local state at Minimum.
	Value headless.Accessor[int]
	// Minimum and Maximum are inclusive and may be equal.
	Minimum, Maximum int
	// Step is the keyboard increment. Zero means one.
	Step int
	// Label names the value at the left of the track and in semantics.
	Label string
	// Keys maps slider actions. Nil uses the headless defaults.
	Keys *keymap.Map
	// Format renders the value at the right. Nil uses strconv.Itoa. It runs during
	// drawing and must be observationally pure.
	Format func(int) string
}

type Sparkline struct {
	Theme  Theme
	Glyphs Glyphs
	Values []float64
	// Minimum and Maximum fix the vertical domain when both are finite and
	// Maximum is greater than Minimum. Any other pair derives the domain from the
	// visible samples, which makes the zero value the automatic mode.
	Minimum, Maximum float64
}

type Spinner struct {
	// Theme is the look: the glyph is what the interface is waiting on, and the
	// label is a note about it.
	Theme Theme
	// Glyphs supplies the coverage-aware frames. A set with no frames draws the label
	// alone, following the package-wide rule that zero glyphs invent no furniture.
	Glyphs Glyphs
	// Label follows the glyph, if there is room.
	Label string
	// contains filtered or unexported fields
}

type Status struct {
	Theme  Theme
	Glyphs Glyphs
	// Doing is what is happening, in the present tense — "thinking", "reading
	// main.go", "running tests".
	Doing string
	// Elapsed is shown after the label, receding. Empty shows nothing, which is right
	// until something has taken long enough to be worth reporting.
	Elapsed string
	// contains filtered or unexported fields
}

type Table struct {
	// Theme is the look. A column title is a heading and there is nothing else here
	// with a fixed role: what a row looks like is data, not a look, which is why
	// RowStyle is a function of the row.
	Theme   Theme
	Columns []Column
	// Rows is how many rows there are.
	Rows int
	// Cell returns one cell for a row and column. The value carries both the width a
	// fitted column measures and the painter given its final box.
	//
	// The plain-text case is:
	//
	//	Cell: func(row, col int) kit.Cell {
	//		return kit.LabelCell(kit.Label{Text: data[row][col],
	//			Align: columns[col].Align, Ellipsis: "…"})
	//	}
	//
	// A custom cell uses a Cell literal. Its painter receives the row's base style —
	// a band or selection — because replacing the cells over a filled row without it
	// would erase the band. Cell and Paint are projection callbacks: they may run
	// repeatedly during measurement and drawing and must be observationally pure.
	Cell func(row, column int) Cell
	// Gap is the space between columns. Zero uses one column, which is the least
	// that still reads as two columns rather than one.
	Gap int
	// Header draws the column titles in the first row.
	Header bool
	// Sorted says which column the rows are in the order of and which way round, when
	// they are in an order at all, so the header can mark it — the only way a reader
	// can tell an order from a coincidence.
	//
	// It is a function because that is the shape the answer already has: a table with
	// a cursor answers exactly this, so wiring the two together is
	// Sorted: rows.Sorted. And because the zero value of a column number is a column,
	// which would mark the first one on every table nobody sorted.
	// Sorted may run during drawing and must only observe ordering state.
	Sorted func() (column int, descending, ok bool)
	// Glyphs are the marks beside a sorted column's title. A table given none marks
	// nothing, which is the rule the whole package keeps.
	Glyphs Glyphs
	// RowStyle styles a whole row, for banding or for a selection. It is a pure
	// projection callback and may run during drawing.
	RowStyle func(row int) grid.Style
}

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

type Tabs struct {

	// Theme is the look: the name of the pane showing is the thing the interface is
	// about, and the rest are there for reference.
	Theme Theme
	// Glyphs draw the rule under the strip. A tabs given none draws no rule, which is
	// the rule the whole package keeps.
	Glyphs Glyphs
	// Rule draws a line under the strip, which is what makes a strip of names read as
	// tabs rather than as a row of words.
	Rule bool
	// contains filtered or unexported fields
}

type TabsConfig struct {
	// Theme and Glyphs define the strip appearance.
	Theme  Theme
	Glyphs Glyphs
	// Items are copied into the constructed headless controller.
	Items []headless.Tab
	// Selection is optional caller-owned state. Nil keeps state local.
	Selection headless.Accessor[int]
	// Keys maps tab actions. Nil uses the headless defaults.
	Keys *keymap.Map
	// NoWrap stops movement at the ends. NoRule hides the separator below the strip.
	NoWrap, NoRule bool
}

type Theme struct {
	// Text is body text, and Muted is text present for reference rather than for
	// reading — timestamps, paths, counts.
	Text  grid.Style
	Muted grid.Style
	// Subtle is quieter than muted: structure the eye should skip unless it is
	// looking for it.
	Subtle grid.Style
	// Strong is emphasis within body text.
	Strong grid.Style
	// Heading titles a pane or a section.
	Heading grid.Style

	// Accent marks the thing the interface is about: the active item, the key in a
	// hint, the prompt marker.
	Accent grid.Style
	// Success, Warning, Danger and Info are outcomes. They are the only colours in
	// the interface that carry meaning on their own, which is why there are exactly
	// four of them.
	Success grid.Style
	Warning grid.Style
	Danger  grid.Style
	Info    grid.Style

	// Border draws a frame, and Divider a line between things inside one.
	Border  grid.Style
	Divider grid.Style
	// Selection is the row under the cursor.
	Selection grid.Style
	// Surface is a pane's background, and Sunken a well inside one — a tool's output,
	// a code block.
	Surface grid.Style
	Sunken  grid.Style

	// Added and Removed are the two halves of a diff. Nothing else in the interface
	// uses green and red on a background, so a diff is recognisable at a glance.
	Added   grid.Style
	Removed grid.Style
	// Context is a diff line that did not change.
	Context grid.Style

	// Scrim is what a layer paints over what it covers, so the eye goes to the layer
	// and it is obvious that what is behind it is not the thing to act on.
	//
	// It is the one entry that is not a style, because receding is not a colour: it
	// is mixing with whatever is already there. A style could only have set one
	// colour over everything, which erases the interface underneath instead of
	// dimming it.
	Scrim Scrim
}

type Transcript struct {

	// Content is what to draw.
	Content *headless.Transcript
	// Scroll is where in it the window sits.
	Scroll *headless.Scroll
	// Keys maps scrolling actions. Nil reads through
	// [headless.DefaultScrollKeys]. It is used only when Scroll is non-nil.
	Keys *keymap.Map
	// Selection picks out cells the user dragged over. Nil selects nothing.
	Selection *headless.Selection
	// Sticky pins a header above the window. Nil pins nothing.
	Sticky *headless.Sticky
	// Matches are highlighted where they fall inside the window, and Current is the
	// index of the one being stepped to, which is drawn differently. Matches must be
	// in row order and non-overlapping; [headless.Result.Matches] already has that
	// shape. The order is what lets drawing depend on the visible window rather than
	// on the age of the session. A Current outside the matches means none is current.
	Matches []headless.Match
	Current int

	// Theme is the look. Every part of a transcript has a fixed role in one — a
	// selection is the selection, the match being stepped to is the accent, a pinned
	// header sits on a surface — so there is nothing here to choose between.
	//
	// A caller who wants one of them different passes a theme with that role
	// changed, which is one line and keeps the look in the one place a look lives:
	//
	//	quiet := theme
	//	quiet.Selection = quiet.Sunken
	Theme Theme
	// Glyphs are the characters the rule under a pinned header is drawn with, which
	// is a fact about the terminal rather than about the look.
	Glyphs Glyphs
	// contains filtered or unexported fields
}

type Tree[T any] struct {
	// Text is what a row says. A tree given none draws nothing but its marks, which
	// is what an item that cannot be read as text comes to. Text runs during drawing
	// and must be an observationally pure projection.
	Text func(item T) string
	// Theme is the look, and Glyphs are the marks beside a branch. A tree given no
	// glyphs draws no marks, and its rows are then told apart by their indent alone.
	Theme  Theme
	Glyphs Glyphs
	// Indent is how many columns a level is worth. Zero uses two.
	Indent int
	// contains filtered or unexported fields
}

type TreeConfig[T any] struct {
	// Theme and Glyphs define row and branch appearance.
	Theme  Theme
	Glyphs Glyphs
	// Controller owns hierarchy, selection and interaction and is required.
	Controller *headless.Tree[T]
	// Text projects an item into its row label. Nil produces an empty label. It runs
	// during drawing and must be observationally pure.
	Text func(item T) string
	// Indent is the columns per depth. Zero means two.
	Indent int
}