Skip to content

JavaScript Architecture ​

src/js/adminvora.js is the runtime: one file, with no build step, no dependencies and no import statement at the top level. A page includes it with one <script defer> tag and every hook in the markup becomes live.

There is no module registry, no store and no ctx object: the public API below is the whole surface.


What ships ​

FileIn dist/What it is
src/js/adminvora.jsyesThe component runtime. This is what a customer installs.
src/demo/demo.jsno33 controllers driving the demo screens — the mail client, the chat, the checkout, the CRM boards. It ships beside the demo pages only.

npm run check:runtime-split holds the boundary: it fails if the runtime names one of the 36 controllers, if the demo file reaches a runtime private that is not on the documented seam, if the seam grants something nobody takes, or if a controller is defined and never called. Nothing in src/demo/ is API, and no page you build should load it.

Why it is one file ​

The runtime is deliberately zero-build: no bundler, no transpiler, nothing resolved at serve time. The cost is that the whole runtime arrives on every page, including the login screen, and Performance states it rather than averaging it away. What is deferred is the expensive part — no page downloads ApexCharts, Tabulator, Quill, CodeMirror or Leaflet unless it carries the hook that needs one.


The public API ​

The runtime publishes one object, window.AdminVora. Everything else in the file is closure-private and unreachable.

MemberShapeWhat it does
versionstring'1.0.1'.
init(root = document)fnRe-scans root and binds any per-element module it finds. The re-scan hook a router calls after a navigation.
destroy(root = document)fnDisposes vendor instances under root and releases their claims. Read Teardown before relying on it.
on(name, fn)fnSubscribes to a runtime event. Returns nothing; there is no unsubscribe.
emit(name, detail)fnNotifies subscribers, then dispatches a CustomEvent on document.
themeobjectget(key), set(key, value, opts), apply(prefs, opts), toggle(), reset(), save(). See Theme Engine.
toastobjectshow(opts), success, error, warning, info, dismissAll().
confirm(options)fn to Promise<boolean>Opens a modal <dialog> and resolves to the reader's answer.
loadingobjectstart(el), stop(el) — the busy state on a button: aria-busy, aria-disabled, width pinned, optional data-av-loading-text. See Buttons & Actions.
a11yobjectannounce(message, priority = 'polite') — one shared live region.
utilsobjectformatCurrency(amount, currency = 'EUR', locale).

An eleventh property, _internal, is attached non-enumerably. It is the five-helper seam src/demo/demo.js reaches through, it is documented in the runtime as unversioned, and it is free to change in a patch release. It is not API, it does not appear in Object.keys(), and the only file permitted to read it is one that never reaches a customer.

js
AdminVora.toast.success('Invoice sent');

const ok = await AdminVora.confirm({
  title: 'Delete this API key?',
  text: 'Any integration using it stops working immediately.',
  accept: 'Delete key',
  variant: 'danger'
});

AdminVora.a11y.announce('Twelve results');
document.querySelector('#total').textContent = AdminVora.utils.formatCurrency(1240, 'EUR');

What is not on it ​

There is no module registry, reactive store, resolved config object or lifecycle promise, so there are no members exposing them: no instance getter or factory, no registration call, no one-shot or unsubscribe form of the event bus. Calling a name that is not in the table above throws "is not a function". npm run check:api-surface fails the build if a documentation page prints such a call.

npm run check:globals covers the other half — a window.__AV_* name a page tells a reader to set must be one the runtime reads.


Boot ​

The runtime is a single IIFE and boots during its own execution. Loaded with defer, it runs at readyState === 'interactive', so it does not wait for DOMContentLoaded — it calls init() on the spot.

publish window.AdminVora           ← before init(), not after
init()
├─ page singletons                 ← customizer, auth, shell, nav bar, OTP,
│                                    password strength, resend, dropdowns,
│                                    tooltips, command palette
├─ initContent(document)           ← per-element modules; see below
│   └─ emit('av:content', { root })
├─ animated icons, shortcuts, actions
├─ emit('av:boot', {})
├─ double rAF → remove .av-booting ← transitions become live after first paint
└─ emit('av:ready', {})

Publishing the API before init() is load-bearing. Modules run during the scan, and a page that declares data for one and formats it with AdminVora.utils calls back into the object as the module's first act — while the file was publishing at the end, that threw a ReferenceError into a console nobody was reading.

Boot is two tiers, and which tier a behaviour is in decides whether a re-scan touches it:

  • Per-element, bound by initContent(root) — modals, datagrid, grid filters, virtual lists, charts, tabs, clipboard, password toggles, money formatting, validation, form helpers, wizards, collapse, relative time, ratings, drawers, context menus, and the vendor-backed fields. These are re-bound by AdminVora.init(root).
  • Delegated or singleton, mounted once for the page's life by init() — dropdowns, tooltips, theme triggers, the shell, the nav bar, the Customizer, the command palette, keyboard shortcuts. AdminVora.init(root) does not touch these, and a document-level listener guards itself with a flag so a second boot cannot bind it twice.

The demo file loads first, and the order is asserted ​

Because the runtime boots during its own execution, a file that subscribes to av:content or av:boot after the runtime has run subscribes after both have already fired: no error, no console output, and 36 screens that quietly do nothing. Every demo page therefore loads demo.js before adminvora.js, and tests/pages.mjs records the request order of both files and fails if it inverts.

This matters to you only if you write a file that listens for those two events. Product code should not — they are a seam with one subscriber, not an extension point.


How an element claims a module ​

Every per-element module calls one helper, and it is the whole re-scan contract:

js
scan('[data-av-datagrid]', 'datagrid', root);

scan() collects matching elements under root (including root itself, which querySelectorAll would skip), then filters out any element whose data-av-init attribute already lists that key — and adds the key to the ones that survive. So:

  • Calling AdminVora.init(el) twice binds nothing twice.
  • A module that loads a vendor claims its elements before the await, so two scans racing the same dynamic import cannot both bind. If the import then fails, the claim is released again — otherwise one offline moment would leave the control permanently inert under a router that re-inits on every navigation.
  • AdminVora.destroy(root) removes the claims it disposes, so markup that is moved rather than destroyed can be initialised again on arrival.
html
<div data-av-datagrid data-av-init="datagrid">…</div>

data-av-init is written by the runtime. Do not author it; an element that arrives already claiming a module will never be bound.


Configuration ​

There is no config object and no options argument. The runtime reads exactly three keys from window.AdminVoraConfig, and npm run check:config-keys fails the build on a fourth appearing in any customer-facing file.

KeyRead byPurpose
rootthe command palettePath prefix for the search index, so a page nested three folders deep resolves the same URLs as one at the root.
palette.sourcesthe command paletteReplaces the built-in list of searchable page groups.
virtualthe virtual-scroll moduleRow data for a named list, keyed by the value of data-av-virtual.
html
<script>
  window.AdminVoraConfig = Object.assign(window.AdminVoraConfig || {}, { root: '../../' });
</script>

Set it before the runtime's <script> tag. One further global exists and is not part of this object: window.__AV_ASSET_BASE__ overrides where vendor chunks are fetched from — see the loader.

Per-module options ​

Options are read straight off dataset at each module's own hook, with no shared parser and no type coercion. An attribute is a string unless the module that reads it converts it.

html
<section class="av-card" data-av-datagrid data-av-grid-noun="order" data-av-grid-per-page="10">
  <table class="av-table">…</table>
</section>

The hook goes on the container the module owns, not on the <table> inside it — the grid renders a toolbar, a search field and a pagination bar as siblings of the table.

Three modules accept a whole options object as JSON instead, because their surface is too wide for one attribute per setting — data-av-datagrid-options, data-av-chart-options and data-av-virtual-options:

html
<div data-av-chart="area" data-av-chart-options='{"height":280,"stacked":true}'></div>

Values that a person could type are never interpolated into markup. Anything user-supplied is set with textContent, or the node is cloned from one already in the tree.


The vendor loader ​

Vendors are dynamic-imported from src/vendor/, never a CDN, and cached so ten charts on a page produce one request. Ten keys are registered, one per vendored library:

apexcharts, sortable, tom-select, imask, glightbox, quill, leaflet, tabulator, codemirror, filepond.

Paths are resolved against the runtime's own URL (document.currentScript.src), because a bare relative specifier in a classic script resolves against the document instead — which would break every page that is not at the site root.

html
<!-- Only if your pipeline hashes and relocates the runtime without moving vendor/ beside it -->
<script>window.__AV_ASSET_BASE__ = '/build/js/';</script>

The value is the directory the runtime is served from, not the bundle root, because ../vendor/ is resolved against it. A missing trailing slash is added rather than demanded.

A failed load is surfaced, not swallowed: the key is checked against the registered list, because a silently-wrong key would otherwise leave a control looking enhanced and doing nothing forever.


Events ​

emit(name, detail) notifies the internal subscriber list, then dispatches a CustomEvent with the same name and detail on document.

js
AdminVora.on('av:theme:change', ({ key, value }) => console.log(key, value));

// The same event, through the DOM
document.addEventListener('av:chart:ready', (e) => console.log(e.detail));

The naming is av:<module>:<verb>. These are emitted:

GroupEvents
Lifecycleav:boot, av:content, av:ready, av:destroy
Themeav:theme:change, av:theme:mode, av:theme:reset
Feedbackav:toast:show, av:toast:hide, av:toast:action, av:confirm:accept, av:confirm:cancel, av:confirm:proceed, av:loading:start, av:modal:show, av:modal:hidden
Navigationav:sidebar:toggle, av:sidebar:group-toggle, av:tabs:change, av:palette:open, av:palette:run, av:auth:view
Assistant and tourav:prompt:submit, av:prompt:stop, av:tour:start, av:tour:step, av:tour:end
Formsav:form:valid, av:form:invalid, av:wizard:change, av:repeater:add, av:repeater:remove, av:inline-edit:commit, av:import:commit
Dataav:datagrid:ready, av:tabulator:ready, av:virtual:ready, av:virtual:range, av:virtual:mode, av:sortable:move
Vendor-backed fieldsav:chart:ready, av:select:ready, av:mask:ready, av:editor:ready, av:code-editor:ready, av:uploader:ready, av:lightbox:ready, av:map:ready

Two constraints are worth stating because the specified runtime removes both:

  • Events are dispatched on document, not on the element that produced them. A framework template cannot bind a handler for av:datagrid:ready to the element itself and receive anything; listen on document and read event.detail.
  • on() has no unsubscribe. There is no one-shot form, no removal call and no AbortSignal option. A listener you add lives as long as the page.

Teardown, and what it does not do ​

AdminVora.destroy(root) walks every claimed element under root and does exactly two things:

  1. Disposes vendor instances — the ApexCharts chart, the GLightbox overlay, the Tabulator grid, the Quill editor, the CodeMirror view, the Tom Select control, the Leaflet map, the IMask instance and the FilePond uploader. Nine of the ten vendors. Sortable.js is the exception and it is a gap, not a decision: the runtime constructs it and discards the return value, so there is no handle to dispose. Re-initialising a sortable list under a router leaves the previous instance attached. This is what actually leaks: a chart holds its own ResizeObserver and does not stop when its element leaves the DOM, and an orphaned one writes NaN into SVG geometry. Where a vendor replaced a server-rendered element (the grid's <table>, the editor's <textarea>), it is put back, so the no-JS fallback is still true on a second visit under a router.
  2. Releases data-av-init claims, so the same markup can be initialised again.

It then emits av:destroy with the number of elements released.

It does not detach listeners. The runtime's own listeners on a removed subtree are collected with the nodes, but a listener a module bound to document is not removed by destroy().


Framework interop ​

init(root) and destroy(root) are the whole surface a framework needs, and there is nothing to read an instance back with — an enhanced element is configured by its markup, so change the markup and re-scan.

jsx
// React
function Grid() {
  const ref = useRef(null);
  useEffect(() => {
    const el = ref.current;
    AdminVora.init(el);
    return () => AdminVora.destroy(el);
  }, []);
  return <div ref={ref} data-av-datagrid />;
}
js
// Vue directive
app.directive('av', {
  mounted:   (el) => AdminVora.init(el),
  unmounted: (el) => AdminVora.destroy(el)
});

Because there is no options argument, a change the markup expresses — a different page size, a different noun — is a change to the attribute followed by destroy() and init() on the same element. Details: React, Vue.


Read next: Build Pipeline.

Documentation for @creativeigniter/adminvora