loom & weft
Made for Swift.

Unreleased APIs from PR #2. Not in 0.2.1. Stable 0.2.1 reference.

LOOM Unreleased (PR #2) / TEXT, MARKDOWN, AND EDITING

TextDocument

Each entry has a stable identity, cached layout, and display options. Visible entries are separated by a blank row. Appending/replacing rebuilds affected layouts; resize and restyle rebuild all entries. Hiding removes display rows but retains the source and identity. Collapsing substitutes a summary. Missing IDs usually yield nil, false, or a no-op. Selection coordinates use document rows; subtract viewport origin and add scroll before querying. clear removes entries without reusing previous identities.

Standard inherited Swift protocol operations such as synthesized equality and OptionSet set operations are not repeated. The public declarations below are extracted from the exact source revision listed in the coverage manifest.

Example

var document = TextDocument(width: 60)
let id = document.append("First message", wrapping: .word)
document.replace(id, with: [TextSpan("Updated message")])
document.setCollapsed(true, for: id)
_ = DocumentView(document)
Members on this page

Feature guides and release status

TextDocument

Structure
struct TextDocument

Conforms to: Swift.Sendable, Swift.SendableMetatype.

Cached entry layouts used for drawing, scrolling, selection, and navigation.

Appending or replacing text rebuilds only the affected entry. Scrolling and selection reuse cached geometry. Entry IDs survive reflow and folding.

Source · TextDocument.swift:17

layouts

Instance Property
var layouts: [TextLayout] { get }

Cached layouts, in entry order, including hidden entries.

Source · TextDocument.swift:18

starts

Instance Property
var starts: [Int] { get }

Document row offsets corresponding to entry layouts.

Source · TextDocument.swift:19

width

Instance Property
var width: Int { get }

Width in terminal cells.

Source · TextDocument.swift:20

layoutBuildCount

Instance Property
var layoutBuildCount: Int { get }

Cumulative count of entry layout builds, useful for diagnostics.

Source · TextDocument.swift:21

rowCount

Instance Property
var rowCount: Int { get }

Total visible document rows, including entry separation.

Source · TextDocument.swift:45

init(width:)

Initializer
init(width: Int)

Creates a value with the supplied arguments. Default arguments are shown in the declaration.

Parameters (1)
width
Available columns in terminal cells.
Source · TextDocument.swift:50

append(_:wrapping:options:)

Instance Method
@discardableResult mutating func append(_ text: String, wrapping: TextWrapping = .grapheme, options: TextWrapOptions = TextWrapOptions()) -> TextDocumentEntryID

Appends an entry, separated from its predecessor by one blank row.

Parameters (3)
text
Source text.
wrapping
Grapheme or word wrapping policy.
options
Terminal policies selected when opening.

Returns TextDocumentEntryID.

Source · TextDocument.swift:56

append(_:background:wrapping:verticalPadding:options:)

Instance Method
@discardableResult mutating func append(_ spans: [TextSpan], background: Color = .terminalDefault, wrapping: TextWrapping = .grapheme, verticalPadding: Int = 0, options: TextWrapOptions = TextWrapOptions()) -> TextDocumentEntryID

Appends styled text and returns a stable identity for later updates.

Parameters (5)
spans
Styled source spans, in order.
background
Argument type and any default are shown in the declaration; see the behavior notes above.
wrapping
Grapheme or word wrapping policy.
verticalPadding
Argument type and any default are shown in the declaration; see the behavior notes above.
options
Terminal policies selected when opening.

Returns TextDocumentEntryID.

Source · TextDocument.swift:64

insert(_:before:background:wrapping:options:)

Instance Method
@discardableResult mutating func insert(_ spans: [TextSpan], before target: TextDocumentEntryID, background: Color = .terminalDefault, wrapping: TextWrapping = .grapheme, options: TextWrapOptions = TextWrapOptions()) -> TextDocumentEntryID?

Inserts styled text before an existing entry without changing any existing identities.

Parameters (5)
spans
Styled source spans, in order.
before
Argument type and any default are shown in the declaration; see the behavior notes above.
background
Argument type and any default are shown in the declaration; see the behavior notes above.
wrapping
Grapheme or word wrapping policy.
options
Terminal policies selected when opening.

Returns TextDocumentEntryID?.

Source · TextDocument.swift:83

remove(_:)

Instance Method
mutating func remove(_ id: TextDocumentEntryID)

Removes an entry while leaving every other entry identity unchanged.

Parameters (1)
id
Stable entry/icon identity, not an array index.
Source · TextDocument.swift:100

replaceLast(_:)

Instance Method
mutating func replaceLast(_ text: String)

Replaces the last entry, or appends it when the document is empty.

Parameters (1)
text
Source text.
Source · TextDocument.swift:109

replaceLast(_:)

Instance Method
mutating func replaceLast(_ spans: [TextSpan])

Replaces the last entry while retaining its background, wrapping, and identity.

Parameters (1)
spans
Styled source spans, in order.
Source · TextDocument.swift:114

replace(_:with:)

Instance Method
mutating func replace(_ id: TextDocumentEntryID, with spans: [TextSpan])

Replaces one entry without changing its identity or collapse state.

Parameters (2)
id
Stable entry/icon identity, not an array index.
with
Argument type and any default are shown in the declaration; see the behavior notes above.
Source · TextDocument.swift:123

setVerticalPadding(_:for:)

Instance Method
mutating func setVerticalPadding(_ rows: Int, for id: TextDocumentEntryID)

Changes presentation spacing without changing source text or entry identity.

Parameters (2)
rows
Row count or signed row movement, according to the method.
for
Argument type and any default are shown in the declaration; see the behavior notes above.
Source · TextDocument.swift:142

setWidthLimit(_:for:)

Instance Method
mutating func setWidthLimit(_ columns: Int?, for id: TextDocumentEntryID)

Caps an entry's wrapping width independently of the document viewport.

Parameters (2)
columns
Cell-column count or signed column movement, according to the method.
for
Argument type and any default are shown in the declaration; see the behavior notes above.
Source · TextDocument.swift:153

setTrailingReservedColumns(_:for:)

Instance Method
mutating func setTrailingReservedColumns(_ columns: Int, for id: TextDocumentEntryID)

Reserves terminal cells at the right edge when wrapping an entry.

The reservation follows document resizes and never changes the selectable source.

Parameters (2)
columns
Cell-column count or signed column movement, according to the method.
for
Argument type and any default are shown in the declaration; see the behavior notes above.
Source · TextDocument.swift:166

setDisplayPrefix(_:continuation:for:)

Instance Method
mutating func setDisplayPrefix(_ prefix: TextSpan, continuation: String, for id: TextDocumentEntryID)

Adds a visible, non-copyable prefix to each display line of an entry.

Wrapped and explicit new lines use the continuation prefix. The stored spans, search text, and copied selections remain the original source.

Parameters (3)
prefix
Argument type and any default are shown in the declaration; see the behavior notes above.
continuation
Argument type and any default are shown in the declaration; see the behavior notes above.
for
Argument type and any default are shown in the declaration; see the behavior notes above.
Source · TextDocument.swift:180

setCollapsed(_:for:summary:)

Instance Method
mutating func setCollapsed(_ collapsed: Bool, for id: TextDocumentEntryID, summary: [TextSpan] = [TextSpan("▶ Collapsed")])

Shows a one-line summary in place of an entry while retaining its full source.

Parameters (3)
collapsed
Argument type and any default are shown in the declaration; see the behavior notes above.
for
Argument type and any default are shown in the declaration; see the behavior notes above.
summary
Argument type and any default are shown in the declaration; see the behavior notes above.
Source · TextDocument.swift:192

isCollapsed(_:)

Instance Method
func isCollapsed(_ id: TextDocumentEntryID) -> Bool

Reports whether the entry is currently represented by a summary.

Parameters (1)
id
Stable entry/icon identity, not an array index.

Returns Bool.

Source · TextDocument.swift:204

setHidden(_:for:)

Instance Method
mutating func setHidden(_ hidden: Bool, for id: TextDocumentEntryID)

Removes an entry from layout without removing its source, identity, or fold state.

Parameters (2)
hidden
Argument type and any default are shown in the declaration; see the behavior notes above.
for
Argument type and any default are shown in the declaration; see the behavior notes above.
Source · TextDocument.swift:209

isHidden(_:)

Instance Method
func isHidden(_ id: TextDocumentEntryID) -> Bool

Returns the entry’s hidden state; false for a missing ID.

Parameters (1)
id
Stable entry/icon identity, not an array index.

Returns Bool.

Source · TextDocument.swift:215

setTailPreview(_:for:reservedHeaderRows:omissionStyle:)

Instance Method
mutating func setTailPreview(_ rows: Int?, for id: TextDocumentEntryID, reservedHeaderRows: Int = 0, omissionStyle: Style? = nil)

Limits expanded presentation to the last wrapped rows; nil restores all rows.

Full source remains available through spans and search, including after resize.

Parameters (4)
rows
Row count or signed row movement, according to the method.
for
Argument type and any default are shown in the declaration; see the behavior notes above.
reservedHeaderRows
Argument type and any default are shown in the declaration; see the behavior notes above.
omissionStyle
Argument type and any default are shown in the declaration; see the behavior notes above.
Source · TextDocument.swift:222

setHeadPreview(_:for:)

Instance Method
mutating func setHeadPreview(_ rows: Int?, for id: TextDocumentEntryID)

Limits a prompt to its first wrapped rows while retaining its full source and padding.

Parameters (2)
rows
Row count or signed row movement, according to the method.
for
Argument type and any default are shown in the declaration; see the behavior notes above.
Source · TextDocument.swift:241

hasHeadPreview(_:)

Instance Method
func hasHeadPreview(_ id: TextDocumentEntryID) -> Bool

Returns true if the entry has a configured head-row limit; false for a missing ID.

Parameters (1)
id
Stable entry/icon identity, not an array index.

Returns Bool.

Source · TextDocument.swift:253

entryID(at:)

Instance Method
func entryID(at row: Int) -> TextDocumentEntryID?

Returns the entry that contains or immediately precedes a document row.

Parameters (1)
at
Argument type and any default are shown in the declaration; see the behavior notes above.

Returns TextDocumentEntryID?.

Source · TextDocument.swift:258

entryID(atIndex:)

Instance Method
func entryID(atIndex index: Int) -> TextDocumentEntryID?

Returns the identity at a layout index, including hidden entries.

Parameters (1)
atIndex
Argument type and any default are shown in the declaration; see the behavior notes above.

Returns TextDocumentEntryID?.

Source · TextDocument.swift:264

row(for:)

Instance Method
func row(for id: TextDocumentEntryID) -> Int?

Returns the current first row for an entry identity.

Parameters (1)
for
Argument type and any default are shown in the declaration; see the behavior notes above.

Returns Int?.

Source · TextDocument.swift:270

entryIndex(for:)

Instance Method
func entryIndex(for id: TextDocumentEntryID) -> Int?

Returns an entry's position even when its rows are hidden.

Parameters (1)
for
Argument type and any default are shown in the declaration; see the behavior notes above.

Returns Int?.

Source · TextDocument.swift:275

spans(for:)

Instance Method
func spans(for id: TextDocumentEntryID) -> [TextSpan]?

Returns the full styled content, including when the entry is collapsed.

Parameters (1)
for
Argument type and any default are shown in the declaration; see the behavior notes above.

Returns [TextSpan]?.

Source · TextDocument.swift:280

wrapping(for:)

Instance Method
func wrapping(for id: TextDocumentEntryID) -> TextWrapping?

Returns the entry's wrapping policy.

Parameters (1)
for
Argument type and any default are shown in the declaration; see the behavior notes above.

Returns TextWrapping?.

Source · TextDocument.swift:285

find(_:after:)

Instance Method
func find(_ query: String, after row: Int = -1) -> TextDocumentEntryID?

Finds the next entry containing text, wrapping around at the end.

Search covers the full source of collapsed entries. The caller can expand a found entry before showing its contents.

Parameters (2)
query
Text to search for.
after
Argument type and any default are shown in the declaration; see the behavior notes above.

Returns TextDocumentEntryID?.

Source · TextDocument.swift:293

resize(width:)

Instance Method
mutating func resize(width: Int)

Reflows all entries when the available width changes.

Parameters (1)
width
Available columns in terminal cells.
Source · TextDocument.swift:306

restyle(style:background:)

Instance Method
mutating func restyle(style transformStyle: (Style) -> Style, background transformBackground: (Color) -> Color)

Restyles cached source and collapsed summaries without changing entry identities or text metadata.

A theme change must rebuild layouts already on screen. This also retains folding, tail previews, wrapping, links, and code-block source for later expansion and copying.

Parameters (2)
style
Text/cell appearance.
background
Argument type and any default are shown in the declaration; see the behavior notes above.
Source · TextDocument.swift:319

clear()

Instance Method
mutating func clear()

Removes entries and cached layout/start arrays. Keeps the document width, build counter, and next identity counter.

Source · TextDocument.swift:337

selectedText(_:)

Instance Method
func selectedText(_ selection: TextSelection) -> String

Copies visible source text across entries, retaining their separation.

Parameters (1)
selection
Selection using the containing type’s coordinate convention.

Returns String.

Source · TextDocument.swift:344

wordSelection(at:)

Instance Method
func wordSelection(at point: Point) -> TextSelection?

Finds a word under a document cell, retaining entry-relative wrapping and padding.

Parameters (1)
at
Argument type and any default are shown in the declaration; see the behavior notes above.

Returns TextSelection?.

Source · TextDocument.swift:360

paragraphSelection(at:)

Instance Method
func paragraphSelection(at point: Point) -> TextSelection?

Finds a source paragraph under a document cell, even when it soft-wraps.

Parameters (1)
at
Argument type and any default are shown in the declaration; see the behavior notes above.

Returns TextSelection?.

Source · TextDocument.swift:365

paint(in:scroll:selection:buffer:)

Instance Method
func paint(in area: Rect, scroll: Int, selection: TextSelection?, buffer: inout Buffer)

Draws the visible document rows into the supplied area.

Parameters (4)
in
Argument type and any default are shown in the declaration; see the behavior notes above.
scroll
Number of document/layout rows skipped above the viewport.
selection
Selection using the containing type’s coordinate convention.
buffer
Mutable destination cell grid.
Source · TextDocument.swift:384