Struct Document 

pub struct Document {
    pub root: Node,
    /* private fields */
}

A loaded .rux document: parsed source, imported components (by tag), the script engine, and the current tree.

Fields

root: Node

Implementations

impl Document

pub fn load(path: impl AsRef<Path>) -> Result<Self, String>

Load a document, flattening any failure to a sentence.

pub fn load_checked(path: impl AsRef<Path>) -> Result<Self, LoadError>

Load a document, keeping the failure’s position so a checker can point at it. Document::load is this with the structure discarded.

pub fn from_source(src: &str) -> Result<Self, String>

Process .rux source with no import resolution (used for fallbacks/tests).

pub fn from_source_checked(src: &str) -> Result<Self, LoadError>

Document::from_source, keeping the failure’s position.

The playground needs this: it has no file to point at, so a parse error with no line was all it could ever show, and “something is wrong somewhere” is not much of an editor.

pub fn engine_mut(&mut self) -> &mut Engine

The script engine, for running @tap handlers.

pub fn diagnostics(&self) -> &Diagnostics

What is currently wrong with this document, for the dev overlay.

pub fn set_load_error(&mut self, error: impl Into<String>)

Record that a re-load failed. The tree on screen stays as it was, so the app keeps working while the file is broken; the overlay says so, and marks what you’re looking at as stale.

pub fn clear_stale(&mut self)

Mark the visible tree as not a leftover from before the error, used when the very first load failed, so there is no earlier version being shown.

pub fn replace_with(&mut self, fresh: Document)

Adopt a freshly loaded document’s tree and state, keeping this one’s identity. Used by hot-reload so a successful load clears the error.

pub fn set_focus(&mut self, focus: Option<Focus>)

Focus an input (by r-model), with its caret and selection. None clears.

pub fn interaction(&self) -> &InteractionState

The pointer/focus state pseudo-class selectors match against.

pub fn set_interaction(&mut self, next: InteractionState) -> bool

Update the interaction state (:hover / :active / :focus) and restyle what it affects. Returns whether anything was restyled, so the shell knows whether to repaint, false for the overwhelmingly common case of the pointer moving within the same element.

Only the affected subtree is spliced, not the whole tree: hover moving between two siblings re-cascades their common parent’s subtree, so a caret or selection anywhere else survives by node identity, the same reconcile discipline signal changes use.

pub fn set_viewport(&mut self, viewport: Viewport) -> bool

Tell the document the window size, for @media. Returns whether any query changed answer, i.e. whether the rule set moved and the tree had to be re-cascaded.

A resize fires continuously, and almost every one crosses no breakpoint, so the common case must be free: the media conditions are evaluated at the old and new size and compared, and the tree is only rebuilt when that vector actually differs. A document with no @media at all compares two empty vectors and never rebuilds.

pub fn rebuild(&mut self)

Rebuild the layout tree from the engine’s current state.

pub fn patch(&mut self, changed: &HashSet<String>) -> bool

Apply a set of changed signals in place where possible: re-evaluate the text bindings that read them and write the new strings into their nodes, without rebuilding the tree (so ephemeral state, caret, scroll, survives untouched). Returns false when the change can’t be patched, it touched a signal that drives structure, an attribute, an input value, or a component prop, in which case the caller must rebuild. Nothing is mutated on the false path.

pub fn apply_edit(&mut self, model: &str, value: &str)

Apply an input edit (a keystroke’s new value for model) and reflect it the cheapest correct way: patch the input’s shown value in place, falling back to a rebuild only when model is also read structurally. The caller sets the caret afterward via set_focus.

pub fn apply_edit_in(&mut self, model: &str, row: Option<&str>, value: &str)

apply_edit for an input in a known r-for row.

The row matters because an r-model is recorded as written: inside a list it can mention the loop variable, which only exists in that row’s scope. The scope was captured when the input was built, so this looks it up rather than reconstructing it.

pub fn value_in(&mut self, model: &str, row: Option<&str>) -> String

An input’s current value, read in its own row’s scope.

pub fn apply_handler(&mut self, src: &str) -> bool

Run an @tap handler and reflect its effect the cheapest correct way: patch the changed bindings in place, falling back to a full rebuild only when the change is structural. Returns whether anything changed, so the shell knows whether to repaint.

pub fn apply_handler_in(&mut self, src: &str, instance: Option<&str>) -> bool

Run a handler that was written inside a component instance.

The instance’s state and props are in scope, and whatever the handler leaves them at is written back: that is what makes a component’s own state writable, and what keeps two instances of one component apart.

A change to instance state rebuilds rather than patches. The state is not a signal, so the binding registry has nothing to look it up by, and claiming otherwise would mean bindings quietly missing updates. A component is a subtree, so the rebuild is bounded in practice.

pub fn route(&self) -> &str

The path the document is on, without any query string.

The same thing the route signal holds, so doc.route() and {{ route }} cannot disagree. For the whole address, query included, see Document::location.

pub fn location(&self) -> &str

The whole address the document is on, query string included.

What a URL bar shows and what --route accepts. The history stores this rather than the bare path, so going back to a search restores what was being searched for.

pub fn navigate(&mut self, path: &str) -> bool

Go to path, recording it in the history.

Returns whether anything changed, so the shell knows whether to repaint. Navigating to where we already are changes nothing, which is what makes tapping the current link in a nav bar a no-op rather than a rebuild.

pub fn start_at(&mut self, path: &str) -> bool

Open the document at path instead of at /.

This is what a deep link arrives as: a browser tab opened straight at /user/7, or rux run app.rux --route /user/7. It replaces the history rather than adding to it, so the arrival page is the first page and Back has nowhere to go, which is what actually happened.

Called before the first frame. Calling it later would silently discard wherever the user had got to.

pub fn history_position(&self) -> (usize, usize)

How far along the history the document is, and how long the history is.

The pair is what a host history (the browser’s) needs to mirror this one: the index is stamped into each entry it pushes, and comes back untouched when the user presses Back. See Document::go_to.

pub fn go_to(&mut self, index: usize) -> bool

Move to the history entry at index, without recording a visit.

The browser’s Back button reports where it landed, not which way it went, and it can move several entries at once. Returns whether the document moved; false means the index was out of range or already current, and the caller’s history has drifted from this one.

pub fn replace(&mut self, path: &str) -> bool

Go to path instead of where we are, overwriting the current entry.

What a redirect needs. navigate would leave the redirecting page in the history, so Back would land on it and be redirected forward again, which reads as the Back button being broken.

pub fn back(&mut self) -> bool

Step back through the history. Returns whether there was anywhere to go.

pub fn forward(&mut self) -> bool

Step forward again. Returns whether there was anywhere to go.

pub fn record_scroll(&mut self, offsets: &[Offset])

Remember how far down the current page the user is.

Called once a frame by the shell, which owns the offsets, rather than at each place that could navigate: a navigate() inside a handler moves the history before the shell hears about it, so the position has to have been recorded already. A scroll causes a repaint, so the last frame’s record is current.

pub fn take_scroll(&mut self) -> Option<Vec<Offset>>

The offsets the next frame should adopt, if a navigation has chosen some.

Empty means the top. Taking it clears it, so a frame that has already obeyed does not keep being told.