PUBLIC API / VERSION 3.0.0
Complete API reference.
Stable hooks, exact parameters, supported data attributes, event contracts, design tokens and deployment behavior. No application-runtime dependency.
JavaScript methods
The public namespace is window.Xshna. Include xshna.min.js after the stylesheet. The combined bundle is idempotent at document scope.
| Method / signature | Purpose | Returns | Notes |
|---|---|---|---|
Xshna.init(root = document) | Initialize event delegation and tabs | Xshna | Adds keyboard/click listeners to provided root, idempotently; returns Xshna. |
Xshna.refresh(root = document) | Refresh dynamically added tab groups | Xshna | Re-evaluates tab/panel selection, returns Xshna. |
Xshna.destroy(root = document) | Remove core delegated handlers | undefined | Removes registered core, advanced and pro document listeners when called with document; reinitialization remains supported. |
Xshna.set(root, {theme,design,density,motion,brand}) | Update a scoped design configuration | boolean | Validates allowed enumerations; hex brand computes high contrast black or white button text. |
Xshna.toast(message, options) | Create a text-only notification | HTMLElement | null | type info|success|warning|danger, duration in milliseconds 0 to persist, root matching .xsh-app. |
Xshna.openDialog("#xsh-id", opener) | Open a native modal dialog | boolean | Requires dialog inside xsh-app, focus returned on close. |
Xshna.closeDialog(dialog) | Close a native modal | boolean | Native close event restores focus to opener. |
Xshna.selectTab(group, tab, focus) | Activate a keyboard-managed tab | boolean | Updates aria-selected, tabindex, and hidden panel state. |
Xshna.toggleCollapse(trigger, force?) | Toggle target panel | boolean | The trigger requires data-xsh-collapse="#xsh-panel-id"; force optionally boolean. |
Xshna.accordionOpen(trigger) | Toggle accordion item | boolean | Automatically collapses siblings when data-xsh-single exists. |
Xshna.sortTable(button) | Sort a DOM table | boolean | Supports text, number or date. First tbody only; sorting is local. |
Xshna.filterTable(input) | Filter table rows | number | String matching over row text; returns visible row count. |
Xshna.carouselMove(button) | Move a scroll-snap track | boolean | Next/previous through trigger attributes. |
Xshna.validateForm(form) | Run native HTML constraint checks | boolean | Sets aria-invalid and optional error text; does not contact server. |
Xshna.scrollSpy(element) | Observe scroll location | function | false | Returns disconnect function; uses IntersectionObserver. |
Xshna.refreshAdvanced(root) | Initialize counters/accordion after DOM insertion | undefined | Applies state to newly inserted advanced components. |
Xshna.initAdvanced() | Install advanced interaction listeners | undefined | Idempotent; automatically activated by the complete bundle. |
Xshna.destroyAdvanced() | Release advanced global listeners | undefined | Disconnects managed observers and allows clean reinstallation. |
Xshna.initPro(root) | Enable enterprise component interactions | Xshna | Combobox, client-side paging, wizard and responsive nav; idempotent. |
Xshna.destroyPro() | Release enterprise listeners | undefined | Also called from Xshna.destroy(document). |
Xshna.gridRefresh(table) | Recalculate client-side grid pagination | undefined | Re-run after replacing or changing table rows. |
XshnaIcons.icon(name,{label}) | Create an inline SVG element | SVGElement | null | Requires optional xshna-icons.js; allowlisted icon names only. |
XshnaIcons.mount(root) | Render data-xsh-icon placeholders | undefined | Builds inline SVGs without external sprite fetch. |
XshnaInspector.scan(document) | Scan development markup | Array | Separate, optional debug script; not a WCAG audit. |
XshnaInspector.highlight(root,true) | Draw development guides | undefined | Debug-only visualization, never required in production. |
Configuration and interaction attributes
| Attribute | Values | Behavior |
|---|---|---|
data-xsh-theme | light | dark | auto | Root color mode |
data-xsh-design | precision | editorial | studio | playful | institutional | Visual personality |
data-xsh-density | relaxed | comfortable | compact | dense | Spacing and control density |
data-xsh-motion | none | subtle | expressive | Motion preference |
data-xsh-brand | dynamic | Enable custom brand tokens |
data-xsh-open | #xsh-dialog-id | Open a dialog |
data-xsh-close | presence | Close ancestor native dialog |
data-xsh-tabs | presence | Designate a tab group |
data-xsh-dropdown | presence | Dropdown container |
data-xsh-dropdown-trigger | presence | Dropdown toggle |
data-xsh-toast | message | Render safe text toast |
data-xsh-toast-type | success | info | warning | danger | Toast status |
data-xsh-collapse | #xsh-id | Toggle hidden target |
data-xsh-single | presence | Single open accordion |
data-xsh-sort | text | number | date | Sort table column |
data-xsh-sort-value | text | Override cell sort representation |
data-xsh-filter | #xsh-table-id | Filter row text |
data-xsh-filter-count | #xsh-count-id | Write visible result total |
data-xsh-counter | #xsh-count-id | Character counter |
data-xsh-password-toggle | #xsh-input-id | Toggle password visibility |
data-xsh-select-all | #xsh-container-id | Toggle checkbox group |
data-xsh-validate | presence | Run native form validation |
data-xsh-error-target | #xsh-id | Field error destination |
data-xsh-carousel-next | presence | Next slide |
data-xsh-carousel-prev | presence | Previous slide |
data-xsh-observe | presence | Initialize scrollspy |
data-xsh-status | success | danger | warning | Status dot |
data-xsh-elevation | flat | raised | Card style |
data-xsh-combobox | presence | Combobox wrapper |
data-xsh-paginate | 1-200 | Client-side data-grid page size |
data-xsh-pagination | #xsh-id | Pagination container |
data-xsh-grid-search | #xsh-table-id | Client-side search binding |
data-xsh-wizard | presence | Multi-step form container |
data-xsh-step | presence | Wizard step region |
data-xsh-next | presence | Validate and proceed |
data-xsh-prev | presence | Previous wizard step |
data-xsh-nav-toggle | #xsh-panel-id | Responsive sidebar toggle |
data-xsh-icon | allowlisted icon name | Requires optional inline icon utility |
Custom events
Events bubble and are visible with document.addEventListener('xsh:tab-change', handler). Events do not perform remote requests.
| Event | Detail | When fired |
|---|---|---|
xsh:ready | {version} | Core initialization |
xsh:config-change | {theme, design, density, motion, brand} | Design root updated |
xsh:tab-change | {tabId, panelId} | Tab activated |
xsh:dialog-open | {} | Native modal opened |
xsh:dialog-close | {} | Native modal closed |
xsh:dropdown-open | {} | Dropdown opened |
xsh:dropdown-close | {} | Dropdown closed |
xsh:toast | {type} | Toast dispatched |
xsh:collapse | {expanded} | Collapse state changed |
xsh:accordion-change | {id, expanded} | Accordion toggled |
xsh:table-sort | {column, direction} | DOM sort complete |
xsh:table-filter | {query, count} | Filter complete |
xsh:form-valid | {valid:true} | Form passed checks |
xsh:form-invalid | {valid:false} | Form blocked |
xsh:carousel-change | {index} | Carousel requested next slide |
xsh:select-all | {checked,count} | Bulk checkbox change |
xsh:combobox-open | {} | Combobox expanded |
xsh:combobox-select | {value} | Combobox option committed |
xsh:grid-page | {page,totalPages,rows} | Paged grid updated |
xsh:wizard-step | {step,total} | Wizard navigation |
Core token registry
Override these token values inside the xsh-app root. Generated spacing and typography variables are additionally documented in the distribution source.
| Token | Scope |
|---|---|
--xsh-font | Inherited custom property |
--xsh-font-mono | Inherited custom property |
--xsh-bg | Inherited custom property |
--xsh-surface | Inherited custom property |
--xsh-surface-alt | Inherited custom property |
--xsh-text | Inherited custom property |
--xsh-text-muted | Inherited custom property |
--xsh-border | Inherited custom property |
--xsh-primary | Inherited custom property |
--xsh-primary-hover | Inherited custom property |
--xsh-on-primary | Inherited custom property |
--xsh-primary-soft | Inherited custom property |
--xsh-on-primary-soft | Inherited custom property |
--xsh-success | Inherited custom property |
--xsh-success-soft | Inherited custom property |
--xsh-warning | Inherited custom property |
--xsh-warning-soft | Inherited custom property |
--xsh-danger | Inherited custom property |
--xsh-danger-soft | Inherited custom property |
--xsh-info | Inherited custom property |
--xsh-info-soft | Inherited custom property |
--xsh-focus | Inherited custom property |
--xsh-shadow-color | Inherited custom property |
--xsh-1 | Inherited custom property |
--xsh-2 | Inherited custom property |
--xsh-3 | Inherited custom property |
--xsh-4 | Inherited custom property |
--xsh-5 | Inherited custom property |
--xsh-6 | Inherited custom property |
--xsh-8 | Inherited custom property |
--xsh-10 | Inherited custom property |
--xsh-12 | Inherited custom property |
--xsh-radius-sm | Inherited custom property |
--xsh-radius | Inherited custom property |
--xsh-radius-lg | Inherited custom property |
--xsh-radius-pill | Inherited custom property |
--xsh-shadow-sm | Inherited custom property |
--xsh-shadow | Inherited custom property |
--xsh-shadow-lg | Inherited custom property |
--xsh-space | Inherited custom property |
--xsh-control-height | Inherited custom property |
--xsh-card-padding | Inherited custom property |
--xsh-row-height | Inherited custom property |
--xsh-line-height | Inherited custom property |
--xsh-content-width | Inherited custom property |
--xsh-motion-fast | Inherited custom property |
--xsh-motion-normal | Inherited custom property |
--xsh-motion-slow | Inherited custom property |
--xsh-ease | Inherited custom property |
--xsh-brand | Inherited custom property |
--xsh-brand-on | Inherited custom property |
How to combine modules
<!-- Simple production deployment -->
<link rel="stylesheet" href="/static/xshna.min.css?v=3.0.0">
<script defer src="/static/xshna.min.js?v=3.0.0"></script>
<!-- Scoped root, no global reset -->
<div class="xsh-app" data-xsh-theme="auto" data-xsh-design="precision">
<!-- Semantic HTML + xsh- classes -->
</div>
// Runtime configuration
const root = document.querySelector('.xsh-app');
Xshna.set(root, { design:'institutional', density:'comfortable' });
document.addEventListener('xsh:dialog-open', event => {
console.log('Opened:', event.target.id);
});Security boundaries: Xshna is a presentation library, not an authentication, validation or sanitization service. All application input must be validated server-side. Static tooltips are not safe locations for sensitive data; protect the data in your own application.