Struct Surface 

pub struct Surface {
    pub id: String,
    pub catalog_id: String,
    /* private fields */
}

Fields

id: String

catalog_id: String

Implementations

impl Surface

pub fn scroll(&mut self, id: &str, offset: f32) -> bool

A scroll container scrolled vertically (content offset in px): any overflow: scroll|auto node or a windowed List/Table (moves the window; only the rows entering/leaving change).

pub fn scroll_to(&mut self, id: &str, x: f32, y: f32) -> bool

Both axes. Offsets clamp to the content the last pass measured (a fling past the end lands on the last page, never on blank rows).

pub fn set_surface_scroll(&mut self, x: f32, y: f32) -> bool

Round 2 (§5): the host’s scroll offset of the WHOLE surface (a surface laid out taller than its host viewport, the host scrolls it). Lists without a bounded size window against it; sticky nodes without a scrolling ancestor pin against it. Returns whether anything must lay out again.

pub fn scroll_offset(&self, id: &str) -> (f32, f32)

The current offset of a scroll container.

pub fn set_open(&mut self, id: &str, open: bool) -> Vec<OutEvent>

Open or close an overlay or popup (Dialog, Drawer, Popover, Tooltip, Menu, Select, the pickers, Toast).

pub fn dismiss_toast(&mut self, id: &str) -> Vec<OutEvent>

A Toast’s timeout (or its close button): open: false, dismiss + change.

pub fn event( &mut self, index: u32, event: &str, payload: Option<Value>, ) -> Vec<OutEvent>

An interaction on layout node index: press, change (with a payload such as {value} / {open} / {page}), select, submit, commit, dismiss, contextmenu {x, y}, upload {files}. Local UI state is updated here; bound props write through; on handlers fire.

pub fn hold(&mut self, index: u32, input: &HoldInput) -> Vec<OutEvent>

The node, or the native owning it, is disabled/loading (its own props, a Form’s injection, or the host’s disabled state). VAPP-162 (round-5 contract §9): one pointer / key / focus input on a hold: true Button at layout node index (crate::hold::HoldInput, coordinates relative to the button’s top-left; the box is the last laid-out frame). Fires holdStart / holdEnd / holdCancel, and while held the node carries the pressed state and paints its holdingLabel (a relayout follows every start and stop). Anything but an enabled hold Button: nothing.

pub fn is_held(&self, id: &str) -> bool

Whether a hold Button is held now.

pub fn failing_checks(&self, id: &str) -> Vec<String>

Validation checks of a field evaluated against the data model: the messages of the failing ones. The reference’s failingChecks: a check WITH a condition fails when it resolves to nothing (an unseeded path), null, false or "" (0 passes); a message that is not a string reads $string.invalidValue (round 2).

pub fn submit_form(&mut self, form_id: &str) -> Vec<OutEvent>

Submit a Form: every field’s checks run; any failure → no submit, invalid {errors}, every failing field shows its messages, focus moves to the first and invalidFields is announced. A busy form refuses.

pub fn command(&mut self, command: &SurfaceCommand) -> Vec<OutEvent>

focus {id}, announce {text, live}, scrollIntoView {id}.

pub fn scroll_to_index( &mut self, id: &str, index: usize, align: ScrollAlign, ) -> Vec<OutEvent>

Round 2 (§5): bring item index (DATA order, before a local sort) of the List or Table id into view, aligned, the pinned section header subtracted. Its own, its scrolling ancestor’s or the host’s offset moves (the host’s: OutEvent::ScrollSurface); a windowed list renders the item on the next pass.

pub fn scroll_into_view(&mut self, id: &str) -> Vec<OutEvent>

Scroll every scroll container above id so the node is in view (a windowed row that is not rendered scrolls by its key’s offset).

impl Surface

pub fn layout(&mut self, measure: &mut dyn Measure) -> LayoutOutput

Prepare the tree, then run the batched passes. At most 3 upcall rounds (intrinsics, heights, one correction). The measurer is called in-process with borrowed requests; Self::layout_begin is the same pass as resumable STEPS for a host that must not be called back while the surface is locked (the FFI).

pub fn layout_begin(&mut self, measure_id: u64) -> LayoutStep

Start a layout pass as STEPS: answer LayoutStep::Intrinsics with Self::layout_intrinsics and LayoutStep::Heights with Self::layout_heights until LayoutStep::Done. Same rounds and upcalls as Self::layout; the host measures between the steps without holding the surface.

pub fn layout_abort(&mut self)

Abandon a stepped pass (the host’s measurer failed): the next layout_begin starts clean; the memo keeps what was answered.

pub fn layout_in_progress(&self) -> bool

Is a stepped pass in progress?

pub fn layout_intrinsics(&mut self, answers: &[Intrinsics]) -> LayoutStep

The answers to LayoutStep::Intrinsics, in request order.

pub fn layout_heights(&mut self, heights: &[f32]) -> LayoutStep

The answers to LayoutStep::Heights, in request order.

impl Surface

pub fn new(id: &str, options: SurfaceOptions) -> Surface

pub fn set_formatter(&mut self, formatter: Arc<dyn Formatter>)

Round 2: format numbers, currencies, percents, dates and relative times through formatter (the host’s, built in the surface’s locale and the host’s time zone; or crate::format::ZonedEnglishFormatter at the host’s UTC offset). The core has no zone database: the zone reaches it only through the formatter. The tree re-binds.

pub fn formatter(&self) -> &Arc<dyn Formatter>

The formatter in effect.

pub fn set_clock(&mut self, now_ms: Option<f64>)

Pin the clock relative times read (epoch ms; None = the wall clock). A host re-binds a surface showing formatRelativeTime without now at least once a minute (Surface::tick).

pub fn tick(&mut self)

Re-bind (relative times move): the next layout rebuilds.

pub fn uses_clock(&self) -> bool

Round 2 (§3): whether the surface shows a time that moves with the clock — a formatRelativeTime call without now in the tree or a template, or a Table relativeTime column — so the host calls Surface::tick at least once a minute. false with a pinned clock (Surface::set_clock). O(nodes): ask after a reduce or layout.

pub fn register_extension(&mut self, ext: ExtensionDef) -> Result<(), String>

Register an extension catalog (validated). The tree is re-reduced.

pub fn set_theme(&mut self, theme: Option<Arc<ResolvedTheme>>)

pub fn theme(&self) -> Option<&Arc<ResolvedTheme>>

pub fn effective_theme(&self) -> Option<&Arc<ResolvedTheme>>

The theme with density and contrast applied (what the core resolves against; painters reading tokens should use this one).

pub fn set_mode(&mut self, mode: Mode)

pub fn mode(&self) -> Mode

pub fn settings(&self) -> &SurfaceSettings

pub fn set_settings(&mut self, settings: SurfaceSettings)

Replace every setting at once; the parts that changed take effect on the next layout (a type-size change re-measures).

pub fn set_locale(&mut self, locale: &str)

pub fn set_strings(&mut self, overrides: IndexMap<String, String>)

pub fn set_mode_setting(&mut self, mode: ModeSetting, system_dark: bool)

light | dark | system, with the platform’s current preference.

pub fn set_density(&mut self, density: Density)

pub fn set_contrast(&mut self, contrast: ContrastSetting, system_high: bool)

pub fn set_font_scale(&mut self, scale: f32)

Dynamic Type / font scale (1 = the theme’s sizes).

pub fn set_insets(&mut self, insets: Insets)

pub fn set_pointer(&mut self, hover: bool, reduced_motion: bool)

A hover-capable pointer and the reduced-motion preference.

pub fn set_rounding(&mut self, on: bool)

Android accumulates in dp and rounds once itself; the browser never rounds. Off = fractional frames.

pub fn set_viewport( &mut self, width: f32, height: f32, max_height: Option<f32>, ) -> bool

Surface size. Height ≤ 0 = as tall as the content (a scrolling host). max_height bounds a transcript card; LayoutOutput::overflow says when the content is taller. Returns whether anything changed.

pub fn viewport(&self) -> (f32, f32)

pub fn set_states(&mut self, id: &str, states: Vec<String>) -> bool

Replace a node’s interaction states (hover/pressed/focus/ focus-visible/disabled…). Restyles THAT node only. A hover or a keyboard focus on a Tooltip’s or a hover Popover’s TRIGGER opens it at once (the host owns the open delay); it STAYS open while the pointer (or focus) is on the trigger or on ANY node of its layer. When both are left it closes at once, or — with settings.hover_close_ms > 0 — raises OutEvent::HoverTimer and closes on Self::hover_timeout unless the pointer came back (crossing the gap from trigger to content). The change events are in take_events.

pub fn hover_timeout(&mut self, owner: &str) -> Vec<OutEvent>

A OutEvent::HoverTimer fired: close the hover overlay owner unless its trigger or its layer is hovered (or keyboard-focused) again. Returns the change events (Relayout when it closed).

pub fn set_pressed(&mut self, ids: &[String]) -> bool

The pressed set as a whole (the spike’s set_pressed).

pub fn set_hovered(&mut self, ids: &[String]) -> bool

The hovered set as a whole: ids carry the hover state (recipes’ hover / style :hover resolve through it), every other node loses it. Same effects as Self::set_states (a hover overlay opens).

pub fn set_hover(&mut self, id: &str, hovered: bool) -> bool

One node’s hover on or off, its other states kept (a host’s pointer enter / leave).

pub fn host_states(&self, id: &str) -> &[String]

The interaction states the HOST set on a node (hover, pressed, focus…; Self::set_states), empty when none.

pub fn take_events(&mut self) -> Vec<OutEvent>

Events the core raised outside a call that returns them (a hover opening a tooltip, a live region announcing).

pub fn invalidate_measures(&mut self)

Forget every cached measurement (a font load, Dynamic Type).

pub fn mark_dirty(&mut self, index: u32) -> bool

Forget one node’s cached measurement.

pub fn apply(&mut self, message: &Value) -> Result<ApplyOutcome, String>

Apply one A2UI server→client message (createSurface, updateComponents, updateDataModel, deleteSurface).

pub fn update_components(&mut self, list: Vec<FlatComponent>) -> ApplyOutcome

An updateComponents payload. A2UI: a later update replaces components BY ID and keeps the rest (the TS reference’s SurfaceStore does the same). VAPP-103: O(update) here, the tree reduces LAZILY on the next read (layout, an event, Self::issues), so a surface streamed one component per message costs linear, not quadratic.

pub fn set_nested(&mut self, tree: NestedNode) -> ApplyOutcome

The nested authoring form (fixtures, MCP templates) instead of a flat component list.

pub fn set_components(&mut self, components: Vec<FlatComponent>) -> ApplyOutcome

A flat component list (what updateComponents carries).

pub fn set_data( &mut self, path: &str, value: Option<Value>, ) -> Result<(), String>

Write value at path (None removes). Templates and bindings re-resolve on the next layout. VAPP-103: a refused write (a pointer past the limits, a non-index token or an index past the end of an array) changes nothing and returns the reason.

pub fn data(&self) -> &Value

pub fn root(&mut self) -> Option<&UiNode>

pub fn issues(&mut self) -> &[ReduceIssue]

The reduce issues (plus the build’s: styles, template items), after any streamed update is reduced.

pub fn structure_version(&self) -> u64

pub fn nodes(&mut self) -> Vec<PlacedNode>

Every slot (removed ones as tombstones, so nodes()[i].index == i).

pub fn nodes_at(&mut self, indices: &[u32]) -> Vec<PlacedNode>

The given slots only (a delta’s added + changed).

pub fn node_count(&mut self) -> usize

Live nodes.

pub fn visual(&self, index: u32) -> Option<&Visual>

The resolved visual of one node (after a layout pass).

pub fn visuals(&self) -> Vec<Visual>

pub fn text_style(&self, index: u32) -> Option<&TextStyle>

pub fn layout_node(&self, index: u32) -> Option<&LNode>

pub fn index_of(&self, id: &str) -> Option<u32>

pub fn hover_styled(&self, index: u32) -> bool

Round 2 (VAPP-100): does the node restyle under the pointer? True when its style has a :hover block or its recipe (the native’s own root recipe, its part or macro recipe) has a rule on state: hover that its props match (crate::theme::recipe_reacts_to), in the effective theme. A painter tracks the pointer over these nodes (as over pressables, triggers and fields) and reports hover. Ask again after a theme switch.

pub fn last_frame(&self, index: u32) -> Option<Frame>

pub fn direction(&self) -> Direction

pub fn is_basic(&self) -> bool

Is this surface a basic-catalog one?

pub fn get_data(&self, path: &str) -> Option<&Value>

pub fn strings(&self) -> &StringTable

The built-in string table in effect (defaults + the host’s).

Trait Implementations

impl Send for Surface