Guides / JavaScript API

JavaScript API

A small global interface, delegated event handling, and complete lifecycle control without a dependency manager.

Bootstrap and lifecycle

/* Automatically initializes when DOM is ready. */
window.xsh.ui.version; // "1.1.0"
window.xsh.ui.init(document); // idempotent
window.xsh.ui.destroy(document); // removes registered event listeners
window.xsh.ui.init(myContainer); // for isolated dynamic mounts

The compatibility alias window.XshnaUI is also exported. Avoid initializing both the document and a nested root; select one owner per interface subtree.

Public methods

Method	Result
`init(root)`	Attach delegated interaction listeners once per root.
`destroy(root)`	Detach listeners and allow clean reinitialization.
`toast({type,title,message,duration})`	Show a safe text-only toast; returns a close handle.
`dialog.open(id, trigger)`	Open a native modal and record focus origin.
`dialog.close(idOrElement)`	Close an open native modal.
`tabs.select(tabElement)`	Activate a tab and its associated panel.
`menu.open(shell, focusPosition)`	Open menu and optionally focus the first or last item.
`menu.close(shell, restoreFocus)`	Close menu; optionally return focus.
`combobox.close(shell)`	Dismiss matching results.

Custom events

document.addEventListener("xsh:combobox-change", (event) => {
  console.log(event.detail.value);
});

document.addEventListener("xsh:table-sort", (event) => {
  console.log(event.detail.column, event.detail.direction);
});

Events bubble from their interactive component and are named xsh:dialog-open, xsh:dialog-close, xsh:menu-open, xsh:menu-close, xsh:menu-select, xsh:tab-change, xsh:combobox-change, xsh:table-sort, xsh:segment-change, xsh:page-change and notification events.

Safety and limits

Toast text uses textContent rather than parsing HTML. UI scripts do not send telemetry or use the network. For AJAX-loaded page segments use lifecycle methods with isolated roots. Application-specific persistence, authentication and authorization are intentionally outside the UI runtime.