Helpers for mounting, swapping, and unloading view components — the building
blocks <ui-outlet> is built on,
exposed for app code that needs the same lifecycle without the outlet shell
(e.g. promoting an inline panel to a modal, custom routing, embedded widgets).
| Export | Signature | Description |
|---|---|---|
prepare_view |
(view, options?) => Promise<HTMLElement> |
Resolve a tag name / HTML string / element / promise / async factory into a mounted element. Sets debounced aria-busy feedback while it resolves the factory or promise and awaits el.readyP. |
swap_view |
(container, new_view, old_view?) => Promise<void> |
Animate the old view out, the new view in. Drives data-state through exiting/entering/active. |
remove_view |
(view) => Promise<void> |
Run a view’s exit animation (data-state="exiting") and detach it. The exit portion of swap_view, for when nothing replaces it. |
stop_view |
(view) => Promise<boolean> |
Dispatch 'view-stop-request' (cancellable). If not vetoed, await view.stop?.(). Returns whether the stop succeeded. |
with_load_feedback |
(target, promise) => Promise<T> |
Await promise while toggling aria-busy="true" on target after a delay. Fast resolutions never set the attribute. Overlapping waits on one target keep it busy until the last one ends. |
apply_attrs |
(el, attrs?) => void |
Set/remove element attributes from a map. true → empty attr, false|null → remove, string → set. |
load_feedback_delay |
(el) => number |
Read the load-feedback-delay attribute (integer ms, default 200). Useful when implementing your own feedback wrapper. |
prepare_view options: { attrs?, container?, feedback_target? }.
feedback_target defaults to container; set it to null to disable the busy indicator. Strings starting with < are parsed as HTML; otherwise treated as a custom-element tag name (awaits customElements.whenDefined).
A view exposes its readiness promise as .readyP — .ready is the
boolean companion, so the helpers do not wait for a view that only sets the boolean. The full view
protocol is on the <ui-outlet> page.
prepare_view from a tag namePass a tag name + attrs. The element is created, attrs applied, then mounted into container. Mounting sets data-state="staging" on the element — from this state, swap_view advances to entering and active, so style staging if the view should stay hidden until the swap. Mounting overrides any data-state passed in attrs.
prepare_view from HTML or async factoryStrings beginning with < are parsed as markup (the first root element is mounted). Functions are invoked and may return an element or a Promise.
swap_view transitionsAnimates the old view out via data-state="exiting", then the new view in via data-state="entering", finally settling on data-state="active".
with_load_feedbackToggles aria-busy="true" after a debounce window. Resolutions shorter than the delay never set the attribute, so the UI doesn't flicker on quick operations. Adjust the window via load-feedback-delay="…" on the target (integer ms, default 200).
The helper only sets the attribute — CSS provides the visible indicator, and ui.css
includes one for <ui-outlet>, <ui-dialog> and
.input-group. Style the busy state for other targets yourself, as the stage below
does; a .btn has no busy indicator, so provide a separate visible indicator when using it as the target. For a field example, see
Asking the server.
stop_view — veto and async cleanupDispatches 'view-stop-request' (cancellable). If not vetoed, awaits view.stop?.(). Use this anywhere you'd ask "is the view willing to be unmounted?".
No view yet
apply_attrsA map-based shorthand for setting/removing attributes in one call. true → empty attribute, false|null → remove, string → set.