# Changelog

All notable changes to Neura are documented here. The format follows
[Keep a Changelog](https://keepachangelog.com/); versions follow
[Semantic Versioning](https://semver.org/).

## [0.2.0] — unreleased

### Security

- **Security review across the library, shim, docs site, and delivery
  pipeline.** No exploitable defect was found in the components'
  default rendering paths - every text option was already inserted as
  text. The review hardened the edges around them:
  - `Neura.escapeHtml` is now part of the public API, so consumers have
    a supported escaper for the options that deliberately take raw HTML
    (`bodyHtml`, select `format*`, restful-table `readView`). It escapes
    quotes as well as angle brackets, making it safe in attribute
    contexts - the widespread `textContent`/`innerHTML` round-trip is
    not.
  - Date-picker labels drawn from `Neura.i18n` are escaped before being
    written into the calendar markup, so a translation pack from an
    untrusted source cannot inject markup or break out of an attribute.
  - Element ids are escaped with `CSS.escape` before being used in
    attribute selectors (dropdown, inline dialog, expander), and
    restful-table encodes row ids into request URLs.
  - Keyboard shortcuts refuse to navigate to non-fetchable URL schemes,
    and `AJS.whenIType.fromJSON` only invokes operations from a fixed
    allowlist.
  - `AJS.Cookie` validates cookie names and escapes them before use,
    restoring protection AUI's design provided implicitly; cookies are
    written with `SameSite=Lax`.
  - Docs examples no longer model unescaped interpolation of fetched
    data - the dropdown and inline-dialog lazy-load samples build nodes
    and set `textContent`.
- **Docs site headers.** The site's security headers were defined but
  never sent: nginx drops inherited `add_header` directives in any
  location that sets one of its own, and every location did. They are
  now included in each location and verified in a test. The site also
  sends a Content-Security-Policy, and `Cross-Origin-Opener-Policy` was
  added.
- **Published integrity hashes now work.** The SRI manifest was written
  to the site root while the CDN page fetched it from `/cdn/`, so the
  integrity table was empty in every built image. The hashes are
  verified to match the bytes the CDN actually serves.
- **Zero known vulnerabilities in the dependency tree** (the library
  itself has no runtime dependencies). Build tooling was updated to
  clear three advisories in dev-only packages.
- A [security policy](SECURITY.md) documents the escaping model, which
  options take raw HTML, and how to report a vulnerability privately.

### Added

- **Responsive header fixed** (three bugs found by a docs-vs-source
  audit): the primary-nav lookup only matched a wrapper-div markup form,
  so the overflow-into-More behavior silently never activated on the
  canonical `<ul class="neura-nav">` markup; `refresh()` wiped the
  overflow menu with `innerHTML`, losing items that should return to
  the bar on a partial resize; and `destroy()` removed the menu with
  overflowed items still inside, deleting them from the page. The
  available-width math now measures the secondary nav's width against
  the container edge (its left edge is meaningless mid-measurement when
  the float wraps). New Playwright spec covers the full
  collapse/restore/destroy cycle.
- **Editor metadata + playground + SRI** — the package now ships
  `web-types.json` (IntelliJ-family IDEs autocomplete every `neura-*`
  class with doc links, straight from node_modules) and a VS Code
  snippets file with the common skeletons. The docs site gained a
  **Playground** (edit markup, preview against the real bundles with
  auto-init live, theme switcher) and the CDN page publishes
  **Subresource Integrity hashes** for the version-pinned files. The
  npm package metadata is publish-ready: proper `exports` with the
  `types` condition, complete `files` list, side-effect marking.
- **Recipes** — a new guide page of complete, tested patterns for
  server-rendered apps: confirming a destructive action (declarative
  `data-confirm` triggers, one delegated listener, text-safe content,
  POST semantics), loading a form into a dialog (wired via the
  bubbling `neura-dialog-show` event), and mapping server validation
  errors onto form fields. Every recipe runs live with exactly the
  code shown and is covered by its own browser spec.
- **Migration scanner / codemod** — `npm run migrate -- <dir>` scans
  any AUI 5.4 codebase and reports every `aui-*` class and `AJS.*`
  call with a verdict: mechanical rename (applied by `--write`),
  covered by the shim, dead even in AUI, deliberately unported, or
  unknown (`--strict` turns unknowns into a CI failure). The mapping
  is parsed from the shim source itself, so the report cannot drift
  from the library. `AJS.*` calls are never rewritten automatically;
  the report names the Neura target for each.
- **TypeScript definitions** — `neura.d.ts` ships in the flatpack, the
  zip, and the CDN: the full `Neura.*` API typed (instance methods,
  option shapes, event names) plus the `window.Neura` global, giving
  autocomplete and checking in TypeScript and plain-JS editors alike.
  Compile-checked in CI against a usage fixture. The legacy `AJS`
  facade stays deliberately untyped.
- **`Neura.debug` - dev-mode diagnostics** — opt-in markup-contract
  warnings (`<html data-neura-debug>` or `Neura.debug(true)`;
  `Neura.debug.scan(el)` for injected content). Neura now tells you,
  with the fix in the message, when a trigger's `aria-controls` points
  nowhere, tooltip text sits in the wrong attribute, a tabs link has
  no pane, a dialog has no id, or a closeable message has no close
  control. Zero cost when disabled.
- **Docs example validation** — a new repeatable harness
  (`npm run validate:docs`) verifies every code panel on every docs
  page: JavaScript snippets must parse, `Neura.*`/`AJS.*` calls must
  resolve against the real runtime surface, HTML snippets may only
  reference classes that exist in the built stylesheet (or documented
  semantic markers), and CSS snippets are checked for balance and
  real token names. A companion crawl clicks every demo trigger on
  every page watching for console errors, and a mirror check compares
  HTML panels against the rendered demos. The full pass found and
  fixed: a wrong checkbox wrapper class in the kitchen sink, a JSON
  exchange example mislabeled as JavaScript, and the sortable-table
  demo not exercising the unsortable-column modifier its snippet
  documents (it now has an Actions column).
- **Brand: derived color system** — the accent palette is now
  generated, not hand-picked: every brand stop derives from the single
  anchor `#3f3d9c` via Neura's OKLCH ramp formula
  (`scripts/derive-palette.mjs`), with lightness solved against WCAG
  contrast targets, chroma clamped to gamut, and the visited-link hue
  fixed at an owned purple; the built-in themes are the same formula
  at other hues. Contrast improves along the way (white on primary
  buttons: 3.9:1 → 4.6:1 top stop, 6.0:1 bottom). The docs site gained
  Neura's mark — the "nerve thread" N (one continuous stroke, a node
  at each synapse end) as favicon and header brand. Two new guide
  pages articulate the identity: **Design principles** (the two-era
  strategy: parity now on purpose, the Neura visual language at 2.0,
  plus the six principles and the color-system contract) and **How
  it's built** (the verification culture: pixel-diffed parity,
  source-executed behavioral contracts, three test layers).
- **AJS window event bus made faithful — the portal's dialog lifecycle
  works under the drop-in.** A source-level audit of the Nsys portal
  found its single most load-bearing integration: AUI's
  `AJS.bind/trigger` are jQuery(window) events, legacy `AJS.Dialog`
  broadcasts `show.dialog`/`hide.dialog`/`remove.dialog` there, and six
  portal plugin files hook `show.dialog` (keyed on `data.dialog.id`) to
  wire the forms inside ajax-loaded dialogs. The shim's bus was a
  private EventTarget and the events were never fired — every
  dialog-hosted validation flow and the dashboard gadget editor would
  have gone silently dead. `AJS.bind/unbind/trigger` now route through
  `jQuery(window)` whenever jQuery is present (CustomEvent fallback
  otherwise), and the legacy Dialog fires all three lifecycle events
  with `{dialog}` payloads, in AUI's order.
- **Migration file map corrected** — the portal decorator loads SEVEN
  files from the AUI block, and the docs said `aui-dependencies.js`
  "can be blanked". Wrong: it bundles jQuery UI 1.8.24, which dashboard
  gadget drag-reordering depends on — blanking it breaks that silently.
  The drop-in path (CLAUDE.md, compatibility-page checklist, llms.txt)
  now lists all seven files with the correct action per file: swap
  `aui.css`/`aui.js`, blank `aui-experimental.{css,js}` + `aui-soy.js`
  (their load-bearing parts — table sorting, the icon font — are
  covered), keep `aui-dependencies.js` as-is.
- **`AJS.debounce`** — an audit against AUI's helper-functions doc found
  it missing from the shim (it's real in AUI 5.4 core); ported with
  AUI's exact semantics (trailing-edge, preserves `this`/args, wrapper
  returns the last completed result). The page's other helper,
  `$.fn.isDirty`, stays unported by design: it was a jQuery plugin the
  portal's flatpack never bundled, so no Nsys-era code can call it.
- **`AJS.template` shim made faithful to AUI's contract** — the previous
  minimal fill-in interpolated values RAW; AUI's `.fill()` HTML-escapes
  every value (that's its safety contract — legacy code passes untrusted
  data through `{key}` tokens assuming escaping), so the drop-in could
  reintroduce XSS in un-audited plugin code. Now verified against the
  original template.js: escaping by default, per-value raw opt-in via a
  `"key:html"` data key, path (`{a.b}`, `{a["x y"]}`) and call
  (`{fn()}`) tokens, chainable partial fills (unresolved tokens
  survive), `fillHtml()`, callable/stringifiable result, and
  `AJS.template.load()` for `<script type="text/x-template">` blocks.
  `AJS.escapeHtml` also gained AUI's backtick escaping. No Neura-native
  equivalent, deliberately — new code uses JS template literals.
- **Docs: AUI example parity** — page-by-page comparison against the
  original AUI 5.4 docs: ported its example patterns (dialog with
  sidebar navigation, toolbar2 grouped actions with dropdowns,
  progress-indicator toggle, tracker links/inverted variants, project
  avatars, nav section headings, entire-page skeleton with footer, and
  a login demo matching the real portal), and synced every page's
  HTML/JS panels 1:1 with the rendered demos.
- **Docs: kitchen sink** — a one-page style-guide / smoke-test view
  (the role AUI's "all in" page played): every component rendered once
  with working triggers, each section linking to its reference page.
  Pairs with the docs top bar — pick a theme or flip RTL and eyeball
  the whole library at once. A Playwright smoke spec loads it and
  asserts zero console errors + initialized components, which
  immediately caught (and fixed) the sandbox-wide missing favicon —
  every page 404'd /favicon.ico; the shared shell now injects an
  inline SVG one.
- **Docs: component matrix** — the components overview now has an
  at-a-glance reference table of the full surface (the role AUI 5.4's
  components matrix played, with Neura-shaped columns): kind (CSS /
  CSS + JS), `Neura.*` entry point, auto-init selector, AUI 5.4 status
  (parity + shimmed spellings vs Neura-native) and since-version. The
  overview card grid also gained the missing Page, Typography, and
  Utilities cards.
- **Docs: Typography reference** — new page for the element-level type
  system (heading scale table, the 10px vertical-rhythm rules, inline
  semantics, the `--neura-font-family` override recipe), mirroring AUI
  5.4's typography doc.
- **Docs completeness audit** — swept every component's implementation
  against its reference page; ~60 implemented-but-undocumented items
  documented (tabs' `activate`/`activateById`, dropdown2/dialog2
  `isOpen`, select's full method/event/CSS surface, sidebar
  `localStorageKey`, shortcuts named-key list, tracker links/inverted/
  width guidance, `neura-box-shadow`, contextual styling rules, etc.)
  and four stale docs claims corrected (flex-vs-table page panel, base
  zebra striping, icon-small, spinnerStop scope).
- **Legacy-markup parity sweep** — audited every unprefixed class in
  AUI 5.4's stylesheet (the class-level audit only covered `aui-*`
  names, so contextual helpers like `form.aui .group` were invisible
  to it) against actual Nsys template usage. Fixed under the drop-in:
  `.hidden` / `.assistive` utilities (used by login.vm/macros.vm — an
  unaliased `.hidden` rendered hidden content), legacy message icon
  spans (`.icon-info/success/warning/error` in login/logout/forgot-
  password/admin templates — icons vanished entirely), the legacy
  message close span (`.icon-close` was invisible — the button-reset
  alias erased its mask fill — and unclickable; `Neura.message` now
  binds it like dialog2 binds legacy close buttons), and
  `.aui-message.shadowed`.
- **Form parity fixes** (computed-style diff of AUI's canonical form
  markup under `aui.css` vs `neura.css`): new
  `.neura-fieldset-group` construct (AUI's `fieldset.group` + floated
  legend — the a11y-correct radio/checkbox grouping); the shim now
  aliases `form.aui` `.group`/`.radio`/`.checkbox`/`.button`/
  `.cancel`/`.buttons`, which previously lost their layout entirely
  under the drop-in; the required-field asterisk now matches AUI's
  5×5px ink exactly (was ~7px).

- **Docs: developer-experience batch** — a Getting started guide
  (artifacts, copy-paste boilerplate, auto-init model, jQuery/AJS
  notes), an Accessibility reference (keyboard tables per component,
  screen-reader semantics, reduced-motion/forced-colors, RTL), a Design
  tokens reference (all 62 `--neura-*` tokens with live swatches and
  the theming surface), live docs search in the top bar (filters the
  sidebar; Enter opens the first match), Copy buttons on every code
  block, and a generalized step-by-step AUI → Neura migration checklist
  on the compatibility page.
- **`Neura.progress`** — JS driver for the progress indicator, promoted
  from the AUI shim: `update(0..1)` sets the fill width, `data-value`,
  and `aria-valuenow` in one call (plus `role="progressbar"`);
  `setIndeterminate()` restores the animated bar; `value()` reads back.
  `AJS.progressBars.*` are now compat aliases — `update()` used to set
  only `data-value` and leave the width to the caller; it now drives
  the width too.
- **`Neura.message.create`** — dynamic inline-message creation
  (`{type, title, body|bodyHtml, closeable, context}`): builds the
  markup with the per-variant icon and a live-region role, appends into
  `context` (or returns unattached), and returns the message instance.
  The `AJS.messages.*` creators are now compat aliases over it and gain
  the per-variant icon; titles are inserted as text (not HTML).
- **Inline-help form pattern** — the forms docs now show the
  consumer-side help-icon toggle (hidden description + `aria-expanded`),
  wired live on the Email demo field; `AJS.inlineHelp()` remains for
  legacy `.icon-inline-help` markup.
- **`Neura.sortableTable`** — table sorting promoted from the AUI shim
  to a native component: singleton per table, imperative
  `.sort(column, direction)`, `.refresh()`, `neura-table-sort`
  CustomEvent, and `.destroy()`. Headers are now keyboard-operable
  (focusable, Enter/Space) in addition to click. Auto-inits on
  `table.neura-table-sortable`; `AJS.tablessortable.setup()` is now a
  compat alias that normalizes legacy `aui-*` marker classes and
  delegates — behavior for existing markup is unchanged.
- **Docs completeness** — reference pages (+ llms.txt sections) for the
  nine previously undocumented CSS-primitive components: lozenges,
  badges, avatars, labels, expander, progress, panels, toolbars,
  quicksearch. The sidebar now lists the full component surface.
- **Full RTL layout support** — set `dir="rtl"` on `<html>` (or a
  subtree) and everything mirrors: the entire stylesheet uses CSS
  logical properties (LTR rendering unchanged), popovers align to the
  trigger's inline-start edge, tooltip placement is logical, sidebar
  drag/keyboard resize and horizontal arrow keys in tabs and the
  date-picker grid follow visual direction (ARIA practice). With the
  ar/fa/he/ur packs, those languages are supported end to end. The
  docs site gained an RTL preview toggle.
- **i18n** — `Neura.i18n` localizes Neura's built-in interface strings
  (~14 keys: date-picker buttons and aria-labels, dismiss/loading
  labels, empty states) with 42 built-in locale packs — every EU
  official language, the Nordics (sv, da, nb, fi, is), Hebrew, Serbian,
  and the most-used world languages, incl. zh + zh-Hant (zh-TW/HK/MO
  alias) and a no → nb alias — plus `Neura.i18n.register()` for
  anything else. Locale from `Neura.i18n({locale})` or `<html lang>`. Month/weekday names and
  first day of week come from browser `Intl` — every language works
  there without a pack. Date input format stays ISO.
- **Tooltip a11y** — keyboard (`:focus-visible`) focus now shows the
  tooltip immediately instead of waiting out the 500 ms pointer-rest
  delay. Click still hides/suppresses it (AUI `hideOnClick` parity).
- **Solid messages** — opt-in `.neura-message-solid` modifier giving
  info/warning/success messages the loud banner palette (solid info is
  brand-colored and theme-aware). Defaults stay subtle for AUI 5.4
  visual parity; error was already solid.
- **Banners** — full-width page-top bars for system-wide state
  (`Neura.banner` + static markup with auto-init): announcement
  (brand-colored, theme-aware) / warning / error variants, optional
  close button, `role=alert`/`status` on dynamic banners. Neura-native
  (no `aui-*`/`AJS` alias).
- **Flags** — auto-dismissing toast notifications (`Neura.flag`):
  the stack scrolls when it outgrows the viewport (newest kept in
  view);
  success/info/warning/error types reusing message styling and theming
  (solid banner-palette fill by default — chrome surfaces are solid,
  inline messages subtle; `solid: false` opts out), top-right stacking, `close: 'auto' | 'manual' | 'never'`, hover/focus
  pauses the dismiss timer, `role=alert`/`status` announcements,
  reduced-motion support. Neura-native — the first component beyond the
  AUI 5.4 parity surface (no `aui-*`/`AJS` alias).

## [0.1.0] — 2026-07-25

First release — full parity with the AUI 5.4 surface used by the Nsys
platform, behind Neura-native APIs with an AUI compatibility shim.

### Components

- Layout shell (page panels, navgroups, page header), typography, forms,
  buttons (incl. split and grouped), icons (Lucide-sourced,
  `currentColor` masks), lozenges, badges, avatars, labels, panels,
  toolbars, progress tracker + indicator, quicksearch, expander.
- Overlays and navigation: dialog2 (modal + strict modal), dropdown2
  (incl. checkbox/radio items and header integration), inline dialog,
  tabs, messages, responsive header, tooltip.
- Date picker — dependency-free calendar popover (ISO format,
  configurable first day of week).
- Select — searchable single/multi combobox over a kept-in-sync native
  `<select>`, with pills in multi mode.
- RESTful table — fetch-based CRUD table (inline edit, create row,
  delete, row events).
- Spinner, sidebar (drag/keyboard resizable, persisted width), keyboard
  shortcuts (sequences, combos, guards).
- Shared plumbing: layer manager (z-index, blanket, Esc, outside-click),
  focus trap, singleton-per-element component model, CustomEvent
  dispatch, `data-*` auto-init.

### AUI compatibility

- `dist/neura.css` / `dist/neura.js` are drop-in replacements for the
  AUI 5.4.3 flatpack: 280+ `aui-*` selector aliases and a `window.AJS`
  facade (`dialog2`, legacy `Dialog` v1, `dropdown2`, `dropDown` v1,
  `tabs`, `InlineDialog`, `messages`, `DatePicker`, `expander`,
  `responsiveheader`, `whenIType`, `RestfulTable`, `auiSelect2`,
  `tablessortable`, layer/focus managers, utils, i18n, cookies).
- Verified against the live Nsys portal page-by-page (pixel diff ≤0.07%)
  and against the original AUI flatpack per component.

### Theming

- Neura indigo brand palette (WCAG-checked) replacing Atlassian blues,
  driven by `--neura-*` design tokens.
- Built-in themes — `legacy` (exact AUI 5.4 palette), `teal`, `violet`,
  `graphite` — selected via `data-neura-theme` on any element or
  `Neura.theme()`. Custom themes are a CSS block of token overrides.

### Accessibility

- Keyboard-only (`:focus-visible`) focus rings across all interactive
  elements; full keyboard models for dropdowns, tabs, date picker grid,
  select, sidebar resize.
- Screen-reader semantics: dialog labelling, live-region messages, menu
  roles, combobox pattern, tooltip wiring.
- `prefers-reduced-motion` and forced-colors (Windows High Contrast)
  support, verified under real browser emulation.

### Distribution

- Docs site with live demos for every component at
  [neura.nsys.org](https://neura.nsys.org), including a machine-readable
  [llms.txt](https://neura.nsys.org/llms.txt) for AI coding agents.
- CDN: `https://neura.nsys.org/cdn/neura.{css,js,umd.cjs}` (latest) and
  `/cdn/<version>/…` (pinned), open CORS, source maps included.
- Downloadable flatpack archive (`/cdn/neura.zip`) with LICENSE +
  NOTICE.