Module utils 

A catch all for project-wide macros and general-purpose functions that are not directly related to Perspective.

Modules below crate::utils strive to be single-responsibility, but some reference other crate::utils modules when it helps reduce boiler-plate.

Structs

Completion

A completion handle for message-based public API methods (invariant I6 — see SESSION_CONFIG_COHERENCE_PLAN.md): its ONLY resolution API is Completion::resolve_after, which takes a run future — so resolving a public method’s promise at message-handling time (before the renders it caused have drawn) is unwritable, not merely discouraged. Dropping an unresolved Completion rejects the caller as cancelled.

DebounceMutex

An async Mutex type specialized for Perspective’s rendering, which debounces calls in addition to providing exclusivity. Calling Self::debounce resolves only after at least one complete evaluation of a call that began no earlier than this one — either by running the caller’s own future, or by coalescing onto the single parked trailing runner. At most TWO debounce evaluations are ever outstanding (one running, one parked); every additional concurrent caller resolves without queueing on the lock.

EffectGuard

EffectLedger

The element-scoped ledger of in-flight EFFECTS: every effectful public method (and the internal flows they schedule, e.g. the before-resize presize) registers an EffectGuard for the duration of its async work, whether or not the caller awaited it. flush() resolves only after the ledger drains, so “called before flush” implies “applied before flush resolves”.

PtrEqRc

A thin wrapper around Rc<T> whose PartialEq uses pointer identity (Rc::ptr_eq) instead of deep structural comparison. This makes it suitable for Yew Properties fields that hold large, cheaply-shared snapshots (e.g. ViewConfig, SessionMetadata, Vec<String>).

PubSub

A pub/sub struct which allows many listeners to subscribe to many publishers, without leaking callbacks as listeners are dropped.

RenderGuard

Proof that the bearer is executing inside a DebounceMutex-locked task.

Subscriber

Like a PubSub without PubSub::emit; the reciprocal of PubSub::callback. Subscriber does not keep the parent PubSub alive.

Subscription

Manages the lifetime of a listener registered to a PubSub<T> by deregistering the associated listener when dropped.

WeakScope

A mutable reference for capturing the Scope props arguments, a useful function for tests.

Enums

DragEffect

DragTarget

ModalAnchor

Anchor point enum, ModalCornerTargetCorner

Traits

AddListener

An extension trait for AddListener::add_listener, which we want to take a variety of function-like arguments for readability.

AsBlob

An extension method for converting various js_sys and web_sys types to web_sys::Blob.

CaretPosition

Utilities for caret position. DOM elements have different APIs for this but Deref makes them fall through, so it is important that this method be called on the correct struct type!

CustomElementMetadata

A trait which allows the define_web_component method to create a Custom Element (which must by definition inherit from HTMLElement) from a [wasm_bindgen] annotated Rust struct (for which this trait is implemented).

u32Ext

Trait for the u32::to_formatted_string method.

Functions

await_dom_loaded

An async which awaits the browser’s load event, which is automatically bypassed if document.readyState indicates this has already occurred.

await_queue_microtask

An async version of queueMicrotask(), curiously absent from web_sys.

calc_anchor_position

Calculate the (top, left) position for a modal element given an anchor point, target element bounding rect, and the modal element’s own bounding rect.

calc_relative_position

Given the bounds of the target element as previously computed, as well as the browser’s viewport and the bounds of the already-connected modal element itself, determine the best anchor point to keep the element on-screen.

define_web_component

Register the Custom Element globally.

download

Given a blob, invoke the Browser’s download popup.

posix_to_utc_str

Convert POSIX timestamp to a formatted string.

request_animation_frame

An async version of requestAnimationFrame(), which resolves on the next animation frame.

set_timeout

An async version of set_timeout, which resolves in timeout milliseconds

spawn_owned

Spawn a fire-and-forget task whose ERRORS ARE OWNED: a failure lands in a tracing::error tagged with tag instead of a dangling Promise rejection (which ApiFuture::spawn produces, invisibly to callers and tests). “View already deleted” cancellations are not failures.

str_to_utc_posix

Convert a String datetime representation to a POSIX timestamp.

use_async_callback

Just like use_callback, except convenient for an async result body.