Getting started

Summary

Neura is a modern, zero-dependency UI component library, the successor to AUI 5.4 inside the Nsys Platform. It's plain CSS classes plus a small vanilla-JS runtime: no framework, no build step, no jQuery. A bundled compatibility shim (aui-* class aliases + a window.AJS facade) makes it a drop-in replacement for the AUI 5.4 flatpack, so existing server-rendered pages keep working while new code uses neura-* and Neura.*.

Get the files

Three ways to get Neura onto a page (all deliver identical files):

  1. Hotlink from the CDN: one <link> and one <script> pointing at neura.nsys.org/cdn/. Latest and version-pinned paths are available; see the CDN page for details and caching behaviour.
  2. Download the archive: neura.zip extracts to a neura-<version>/ folder with the files below plus the Apache 2.0 LICENSE and NOTICE.
  3. Vendor the dist files: build from source (npm run build) or copy the archive contents into your project's static assets, as the Nsys portal does with its flatpack.
FileWhat it is
neura.cssThe complete stylesheet: every component, themes, the a11y layer, and all aui-* shim aliases.
neura.jsESM build for <script type="module"> or bundlers. Default-exports the Neura API.
neura.umd.cjsUMD build for classic <script> tags. Exposes window.Neura and window.AJS and runs auto-init - the right choice for server-rendered apps.
neura.d.tsTypeScript definitions for the full Neura.* API. Editors use them for autocomplete and checking even in plain-JS projects.

Your first page

A complete page you can save and open - a primary button, an info message, and a dialog wired up with three lines of JavaScript: 

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>My first Neura page</title>
    <link rel="stylesheet" href="https://neura.nsys.org/cdn/neura.css">
    <script src="https://neura.nsys.org/cdn/neura.umd.cjs"></script>
  </head>
  <body>
    <div class="neura-message neura-message-info">
      <span class="neura-icon neura-icon-info"></span>
      <p class="title"><strong>Welcome</strong></p>
      <p>This page is styled by <a href="https://neura.nsys.org"
        target="_blank" rel="noopener">Neura</a> - no build step, no dependencies.</p>
    </div>

    <div style="text-align: center; margin-top: 24px">
      <button class="neura-button neura-button-primary" id="say-hello">Say hello</button>
    </div>

    <section class="neura-dialog2 neura-dialog2-small" id="hello" aria-hidden="true">
      <header class="neura-dialog2-header">
        <h1 class="neura-dialog2-header-main">Hello</h1>
        <button class="neura-dialog2-header-close" aria-label="Close">
          <span class="neura-icon neura-icon-close"></span>
        </button>
      </header>
      <div class="neura-dialog2-content">
        <p>Your first Neura dialog.</p>
      </div>
      <footer class="neura-dialog2-footer">
        <div class="neura-dialog2-footer-actions">
          <button class="neura-button neura-button-primary" id="hello-ok">OK</button>
        </div>
      </footer>
    </section>

    <script>
      var dialog = Neura.dialog2('#hello');
      document.getElementById('say-hello').addEventListener('click', function () { dialog.show(); });
      document.getElementById('hello-ok').addEventListener('click', function () { dialog.hide(); });
    </script>
  </body>
</html>

The dialog starts with aria-hidden="true" so it stays hidden until show(); Esc and backdrop click close it, and the header close button is wired automatically. Pin a release by putting the version in the path (/cdn/0.2.0/neura.css) - see CDN.

No JS needed for most things

Neura follows AUI's declarative model: static classes plus data-* attributes on server-rendered HTML. The script scans the page on DOMContentLoaded and binds behaviour to matching elements: for most components you write markup and never touch JavaScript. These selectors are auto-initialized:

SelectorComponent
.neura-dropdown2-trigger[aria-controls]Dropdown menus
.neura-messageMessages (wires the close button)
.neura-bannerBanners (wires the close button)
.neura-tabs:not(.neura-tabs-disabled)Tabs
.neura-inline-dialog-trigger[aria-controls]Inline dialogs
.neura-header[data-neura-responsive]Responsive header
.neura-date-picker-inputDate picker
.neura-expander-trigger[aria-controls]Expander
[data-neura-tooltip]Tooltips
table.neura-table-sortableSortable tables

Dialogs are the deliberate exception: they are imperative (Neura.dialog2(el).show()), as in the boilerplate above. Components like flags, spinners, select, and the RESTful table are also created through the Neura.* API.

ES modules

Modern pages and bundlers can use the ESM build instead of the UMD script tag. It runs the same auto-init: 

<script type="module">
  import Neura from './neura.js';
  Neura.dialog2('#hello').show();
</script>

The CDN serves it with open CORS, so import Neura from 'https://neura.nsys.org/cdn/neura.js' works from any origin. The stylesheet is a separate <link> either way.

jQuery and AJS

Neura core has zero dependencies: no jQuery, no framework. For pages built in the AUI era, the bundle includes a compatibility shim: window.AJS (dialog2, dropdown2, messages, tabs, and the rest of the surface Nsys uses) and aui-* aliases for every covered CSS class, so existing markup and callsites keep working unchanged. The shim is a migration bridge, documented on the AUI compatibility page, and will be removed in 2.0 - always write new code as neura-* / Neura.*. jQuery is never required by Neura itself; if your own legacy code uses AJS.$, load your jQuery before the Neura script, exactly as with the AUI flatpack.

TypeScript and editor support

The flatpack ships neura.d.ts covering the whole Neura.* API (instance methods, option shapes, and event names) plus the window.Neura global. In a TypeScript project, point at it once: 

// e.g. in a global.d.ts
/// <reference path="./vendor/neura/neura.d.ts" />

Plain JavaScript projects get the same autocomplete in VS Code and IntelliJ: keep the file next to the vendored dist files (editors pick it up via the types reference), or enable checkJs and import types through JSDoc. The legacy AJS facade is deliberately untyped; new code uses Neura.*.

Two more editor helpers ship with the package: a web-types.json (IntelliJ-family IDEs pick it up automatically from node_modules and offer neura-* class completion inside class="" attributes, each linking to its docs page), and editor/neura.code-snippets - drop it into your project's .vscode/ folder for skeleton snippets (neura-dialog2, neura-field-group, neura-flag, …).

Debug mode

Most integration bugs are markup-contract slips the library can detect: a trigger whose aria-controls points nowhere, tooltip text in the wrong attribute, a tabs link without a pane, a dialog without an id. Debug mode makes Neura warn about them (plain console.warn, with the fix in the message) instead of silently doing nothing: 

<!-- declaratively - scans automatically after auto-init -->
<html data-neura-debug>
// or imperatively
Neura.debug(true);        // enable + scan the page now
Neura.debug.scan(el);     // re-check content you injected later
Neura.debug();            // read the current state

Checks cost nothing when disabled; leave the attribute off in production.

Browser support

Evergreen browsers: the last two versions of Chrome, Firefox, Safari, and Edge. No Internet Explorer support.

Next steps