Skip to content
lazy-cuh

Items and Layout

An item is a semantic object: a setting, channel, log entry, or tree node.

A row is a rendered terminal line. One item may render to one row or many rows.

Navigation should move by item. If an item wraps to three rows, pressing j should move to the next item, not the next wrapped row.

The viewport layer maps item indexes to visual line ranges and visual lines back to item indexes.

ListViewModel composes these pieces:

  • NavigableItem stores semantic item data.
  • render_item turns an item into one or more visual lines.
  • LineNumberSpec controls off, absolute, and relative line numbers.
  • ViewportMap maps rendered lines back to item indexes.

TreeViewModel uses the same rendering and viewport pieces after flattening visible TreeItem nodes. This keeps list and tree behavior aligned.

TextViewModel is not item-navigable, but it still uses the same width and wrapping primitives. TextViewSpec.wrap_mode defaults to MULTILINE, which preserves explicit line breaks and truncates each line to the configured width. Apps can switch to TRUNCATE for a one-line surface or WRAP for folded read-only text.

Textual widgets should use these outputs instead of duplicating layout logic in widget subclasses.

For runtime cursor movement, keymaps, and item action messages, see Navigable Content.