AUI compatibility shim

Summary

The Neura flatpack ships with a compatibility shim that aliases every legacy aui-* class onto its neura-* equivalent and exposes a window.AJS facade with the public methods Nsys's existing code depends on. The goal is a one-step replacement path: drop dist/neura.css and dist/neura.js into nsys-portal-webapp/.../resources/aui/ and existing Velocity templates + plugins keep working unchanged.

What's a "shim"?

A shim is a thin translation layer that sits between two otherwise incompatible interfaces and forwards calls from one to the other. The term is borrowed from carpentry - a small wedge inserted between two pieces to make them fit. In software it's been the term-of-art for back-compat translation layers since the 1990s.

Neura's shim does three concrete things, each implemented as a thin layer that doesn't change either side:

CSS aliasing: every legacy .aui-* selector is @extend-ed onto its .neura-* equivalent (in src/shim/_aui-classes.scss). The browser sees the old class name; the styling comes from the new rules.
JS facade: src/shim/ajs.js installs window.AJS with the same public surface AUI 5.4 had. Most members are passthroughs to Neura.* equivalents.
Legacy v1 builders: older APIs like AJS.Dialog and AJS.dropDown are re-implemented on top of the modern Neura.dialog2 / Neura.dropdown2 components, so plugins that haven't migrated still work without code changes.

We use the technical term shim in source-code comments, file names (src/shim/), and engineering discussions because it's precise. The user-facing label is "AUI compatibility" - same thing, less jargon.

When you need to know about it

Scenario	What the shim does
Dropping into nsys-portal	Velocity templates use `aui-*` class names verbatim; the shim's CSS aliases make them render through Neura rules.
Calling `AJS.dialog2` from `main.js`	`window.AJS.dialog2(...)` is a passthrough to `Neura.dialog2(...)`.
Legacy v1 builders (`AJS.Dialog`, `AJS.dropDown`)	Re-implemented on top of dialog2 / dropdown2 so plugins that haven't migrated still work.
Sortable tables (`AJS.tablessortable`)	Real implementation: clicking `<th>` reorders rows, updates `aria-sort`.
Writing new code	Use `neura-` + `Neura.`. The shim is for back-compat only and will drop at 2.0.

Drop-in test

Everything below uses only legacy aui-* classes and the global AJS API, with no Neura-prefixed names:

aui success aui error

AUI-style dialog

This dialog uses only AUI class names and was opened with AJS.dialog2('#aui-dialog').show(). The shim routes that call to Neura.dialog2 and the aui-* selectors are aliased onto the neura-* rules.

What's aliased (CSS)

112+ legacy aui-* selectors are extended onto the matching neura-* rules via Sass @extend. A non-exhaustive index; the source of truth is src/shim/_aui-classes.scss.

Legacy	Aliases to
`.aui-button*`	`.neura-button*`
`.aui-dialog2*`	`.neura-dialog2*`
`.aui-dropdown2*` / `.aui-style-default`	`.neura-dropdown2*` / `.neura-style-default`
`.aui-message*`	`.neura-message*`
`.aui-tabs*`	`.neura-tabs*`
`.aui-inline-dialog*`	`.neura-inline-dialog*`
`.aui-lozenge` / `.aui-avatar`	`.neura-lozenge` / `.neura-avatar`
`.aui-page-panel` / `.aui-navgroup`	`.neura-page-panel` / `.neura-navgroup`
`.aui-message.error` (compound)	`.neura-message-error` (rewritten as nested rule)
`table.aui` / `form.aui` field hooks	`.neura-table` / `.neura-form`

What's exposed (JS)

window.AJS is installed by the shim (src/shim/ajs.js) at module load. Real implementations cover everything Nsys actually uses; the rest are stubs that console.warn on first call.

Components - passthrough to Neura

AJS	Routes to
`AJS.dialog2(input)`	`Neura.dialog2(input)`
`AJS.dropdown2(input)`	`Neura.dropdown2(input)`
`AJS.tabs.setup()` / `.change(href)`	`Neura.tabs` auto-init / instance switch
`AJS.InlineDialog(trigger, id, fn, opts)`	`Neura.inlineDialog` (legacy callback supported)
`AJS.messages.{success,error,warning,info,hint,createMessage,makeCloseable,makeFadeout,setup}`	`Neura.message`
`AJS.responsiveheader.setup()`	`Neura.responsiveHeader`
`AJS.DatePicker`	`Neura.datePicker`
`AJS.expander`	`Neura.expander`

Legacy v1 - re-implemented

AJS	Notes
`AJS.Dialog`	Full v1 builder API (`addHeader`, `addPanel`, `addPage`, `addSubmit`, `addCancel`, `addButton`, `addLink`, `gotoPanel`, `nextPage`, `prevPage`, etc.) re-implemented on top of `Neura.dialog2`.
`AJS.dropDown`	v1 dropdown; routes to `dropdown2`.
`AJS.tablessortable.setup()`	Real ascending/descending sort by clicking `<th>`; updates `aria-sort`.
`AJS.tables.rowStriping()`	No-op (CSS handles it).
`AJS.layer` / `AJS.LayerManager` / `AJS.FocusManager`	Wired to Neura's internal layer-manager / focus modules.
`AJS.progressBars.update()` / `setIndeterminate()`	Drive the `.neura-progress-indicator` width / animation.

Utilities - real implementations

AJS	Notes
`AJS.escapeHtml(s)`	HTML-escape a string.
`AJS.parseHtml(s)`	Parse a fragment into a Node.
`AJS.format(template, ...args)`	Sprintf-style formatter.
`AJS.template(s)`	AUI's micro-templating, full contract: `.fill(obj)` substitutes `{key}` tokens and HTML-escapes every value (raw insertion is opted into per value with a `"key:html"` data key; the token stays `{key}`); tokens can be paths (`{a.b}`, `{a["x y"]}`) or calls (`{fn()}`); unresolved tokens survive so partial fills chain; `.fillHtml(obj)` substitutes raw; `.toString()` reads the result; `AJS.template.load(title)` reads a `<script type="text/x-template" title="…">` block. Legacy-only; new code should use JS template literals.
`AJS.debounce(fn, wait)`	Trailing-edge debounce (AUI semantics: returns the last completed result).
`AJS.contextPath()`	The web app's context path (defaults to '').
`AJS._addID(el)` / `AJS.id()`	Unique-id generator + auto-stamp.
`AJS.isClipped(el)`	Detect overflow ellipsis.
`AJS.bind/unbind/trigger`	Event wrappers (`addEventListener`-equivalents).
`AJS.toInit(fn)`	Defer to `DOMContentLoaded`.
`AJS.keyCode`	Named keycode constants.
`AJS.log/warn/error`	Console wrappers.
`AJS.I18n.{getText, keys}`	String table accessor (no-op fallback).
`AJS.Cookie.{read, save, erase}`	Document.cookie wrappers.
`AJS.populateParameters()`	Reads `data-*` from a `<meta>` tag into `AJS.params`.
`AJS.$`	Passthrough to jQuery if it's loaded as a peer dep.
`AJS.version`	The Neura version string (so legacy code that asserts on a version doesn't blow up).

Stubs (warn once)

AUI internals that nothing in Nsys actually depends on, but which old plugins might touch in passing: AJS.popup, AJS.dim/undim, AJS.inlineHelp, AJS.whenIType, AJS.setUpToolbars, AJS.drawLogo, AJS.firebug, AJS.warnAboutFirebug, AJS.enable, AJS.onTextResize. Each logs a single console.warn on first call so you know if any code path is still hitting them.

Migration checklist

Migrating an AUI 5.4 application to Neura, step by step:

Scan your codebase first. The Neura repo ships a migration scanner: npm run migrate -- path/to/your/app inventories every aui-* class and AJS.* call you use and gives each a verdict: mechanical rename, covered by the shim, dead even in AUI, deliberately unported, or unknown. The class mapping is parsed from the shim source, so the report can't drift from the library. Add --write to apply the mechanical class renames (commit first; AJS.* calls are reported, never rewritten), --json for machine output, and --strict as a CI gate on unknowns.
Swap the flatpack. Replace your bundled aui.css with neura.css and aui.js with neura.umd.cjs; blank or drop aui-experimental.css, aui-experimental.js, and aui-soy.js (Neura covers their surface, including table sorting and the icon font, which mask-image glyphs replace). Server templates keep the same <link>/<script> tags; only the file contents change. See Getting started for the build artifacts. Caution: if you shipped aui-dependencies.js, keep it - it bundles jQuery UI, and code using .sortable() or other jQuery UI plugins depends on it. Neura replaces AUI, not jQuery UI.
Keep jQuery only if your own code needs it. Neura never requires it. If legacy scripts expect window.jQuery / AJS.$, load jQuery before Neura and the shim passes it through.
Verify the drop-in. Templates with aui-* classes and AJS.* calls keep working unchanged (the tables above are the exact surface). Watch the browser console: deliberately unshimmed AUI internals warn once on first call instead of failing silently.
Custom CSS keeps layering. Overrides written against aui-* selectors (e.g. semantic dialog-header colors) apply to Neura markup identically; the aliases make the selectors equivalent.
Write new code Neura-native. neura-* classes and the Neura.* API only; treat aui-* / AJS.* as frozen legacy. Quick map: swap the aui- class prefix for neura-; AJS.dialog2 → Neura.dialog2, AJS.messages.* → Neura.message.create, AJS.InlineDialog → Neura.inlineDialog, AJS.whenIType → Neura.shortcuts, AJS.tablessortable.setup → Neura.sortableTable, AJS.progressBars → Neura.progress, AJS.DatePicker → Neura.datePicker.
Migrate touched code as you go. When you edit a template or script anyway, convert that block to the Neura surface; converge over time instead of a big-bang rewrite.
Plan for 2.0. The compatibility shim (CSS aliases + window.AJS) is removed in Neura 2.0. Anything still on the legacy surface then will break - the console warnings and the tables on this page are your inventory of what's left.

What's not shimmed

AJS.popup: legacy popup dialog (use AJS.dialog2 or Neura.dialog2).
AJS.bind/unbind on namespaced events (jQuery custom-event style): basic addEventListener wrapping is in place but the namespace syntax is not.