Vyuh Document

Addressing ​

You will learn how to point at content: a Ref<T> names one node and survives edits, a Position is an offset inside a node's text, a Range spans two positions, and a Story is one flow of blocks (the body, a header, a footnote).

Anatomy of an address A one-page mock document in section 0: a header, a body with a heading, a paragraph and a table, a footnote and a footer. Callouts name the address of each part: doc.section(0) for the section; section(0).header and footer for its header and footer stories; body.heading, body.at and body.first for references to blocks; a Range of two Positions, each a block reference and an offset, for the word between offsets 12 and 20; table.cell for a cell; and doc.footnotes.note(0) for the footnote. SECTION 0 Quarterly report BODY Introduction Revenue was stronger this year. 12 20 row 1 · col 1 ¹ Source: annual accounts Page 1 of 4 doc.section(0)Section: page setup, body and its stories section(0).header(HeaderKind.primary)Story · the header body.heading(text: 'Introduction')Ref<Heading> p = body.at<Paragraph>(0)Ref<Paragraph> · element + id Range(start, end)two Positions: ref + offset, 12 → 20 table = body.first<Table>()Ref<Table> table.cell(row: 1, column: 1)Ref<Cell> doc.footnotes.note(0)a footnote, with its own story section(0).footer(HeaderKind.primary)Story · the footer
Every part of a page has an address
dart
final doc = controller.document;

final third = doc.body.at<Paragraph>(2);                  // Ref<Paragraph>
final intro = doc.body.heading(text: 'Introduction');     // Ref<Heading>?
final table = doc.body.first<Table>();                    // Ref<Table>
final b2 = table.cell(row: 1, column: 1);                 // Ref<Cell>
final header = doc.section(0).header(HeaderKind.first);   // Story
final note = doc.footnotes.note(0);                       // Ref<Footnote>
final words = Range(
  Position(third, offset: 12),
  Position(third, offset: 20),
);

Stories ​

GetterStory
document.bodyThe body of every section, in order
document.section(i).bodyOne section's body
document.section(i).header(HeaderKind.primary) / .footer(...)A header or footer (primary, first, even)
document.footnotes.at(i)The ith footnote's story

Each story offers the same queries:

MethodReturns
at<T>(index)The indexth block of element T (Block counts all)
first<T>()The first block of T
where<T>((node) => test)The first match, or null
all<T>()Every block of T, in order

Element packages add their own addressing extensions: Story.heading(text:) (HeadingAddress), Ref<Table>.cell(row:, column:) (TableAddress) and Notes.note(i) (FootnoteAddress).

References survive edits ​

A Ref follows its node when other edits move it. Using a reference to a deleted or missing node fails with NotFound:

text
NotFound: Paragraph 3 in the body doesn't exist: the body has 2 paragraphs.
Ref memberMeaning
existsWhether the addressing found its node
elementThe node's element
descriptionTable t1, used in error messages
toJson(){element, id}, the form agents send

document.read(ref) returns the typed content (Result<T>), for example Paragraph.text or Heading.text.

Re-address after structural edits

A Ref<Table>.cell(...) lookup is resolved in the snapshot the table reference came from. After inserting a row, read the table again from controller.document before addressing the new cell.

Positions and ranges ​

Position(ref, offset: n) is a character offset inside one node's text. Range(start, end) spans two positions in the same node; Range.at(position) is a caret. Text ranges stay inside one block.

Next ​

Commands: what you can do with these addresses.