JavaScript Features

JavaScript Features

The UI bundle contains 9 JavaScript files (713 total lines): 7 upstream Antora files numbered for load order, and 2 vendor files providing custom Domus functionality.

File Inventory

File Lines Load Purpose

01-nav.js

175

Bundled

Sidebar expand/collapse, scroll position memory, keyboard nav

02-on-this-page.js

115

Bundled

TOC highlighting: tracks scroll position, highlights current section

03-fragment-jumper.js

43

Bundled

Hash fragment navigation with smooth scrolling

04-page-versions.js

17

Bundled

Version selector dropdown behavior

05-mobile-navbar.js

20

Bundled

Burger menu toggle for mobile screens

06-copy-to-clipboard.js

80

Bundled

Upstream copy button (superseded by domus-ui.js implementation)

07-breadcrumbs.js

38

Bundled

Breadcrumb trail click handling

vendor/domus-ui.js

182

Separate

Custom: theme toggle, focus mode, code block enhancements

vendor/highlight.bundle.js

43

Async

Pre-built highlight.js bundle for syntax highlighting

Bundled files are concatenated into site.js via Browserify. Separate files are loaded individually by footer-scripts.hbs.

domus-ui.js (182 lines)

The core custom JavaScript file, organized into three subsystems:

Theme Toggle (lines 22-59)

  • createThemeToggle() builds a fixed-position glassmorphism pill (bottom-right, 24px offset)

  • Cycles through 7 themes on click: dark → catppuccin → light → royal → aurora → ocean → ember → dark

  • Each theme has a unique SVG icon and display label

  • Reads/writes antora-theme cookie for persistence

  • Sets data-theme attribute on <html> element

Focus Mode (lines 64-114)

  • createFocusToggle() builds a second pill (bottom-right, offset 140px left of theme toggle)

  • Toggles body.focus-mode CSS class that hides: navbar, nav panel, TOC sidebar, breadcrumbs, toolbar

  • Centers content at max-width 900px with generous padding

  • Keyboard shortcuts: F to toggle, Esc to exit

  • Ignores key events when focus is in <input> or <textarea>

  • Active state: blue gradient background with glow shadow

  • Persists via antora-focus cookie

Code Block Enhancements (lines 119-166)

  • enhanceCodeBlocks() iterates all .listingblock .content elements

  • Adds a toolbar (absolute positioned, top-right) with two elements:

    • Language badge: extracts language from code.className (e.g., language-bash), displays uppercase label with gradient background

    • Copy button: clipboard write via navigator.clipboard.writeText(), green checkmark animation on success (1.5s revert)

  • Skips generic languages: none, text, plaintext, nohighlight

  • Badge styling: #313244 → #45475a gradient, #cdd6f4 text, #585b70 border

Upstream Antora JS

01-nav.js (175 lines)

Manages sidebar navigation state:

  • Expands/collapses nav tree items on click

  • Remembers scroll position in the nav panel

  • Handles keyboard navigation (arrow keys)

  • Auto-scrolls to current page on load

02-on-this-page.js (115 lines)

Powers the right-sidebar table of contents:

  • Observes scroll position via IntersectionObserver

  • Highlights the TOC entry matching the visible section

  • Smooth scroll on TOC link click

03-fragment-jumper.js (43 lines)

Handles URL hash fragments:

  • Scrolls to the target element on page load if hash exists

  • Adjusts for fixed header offset

04-page-versions.js (17 lines)

Version selector:

  • Populates dropdown from component version data

  • Navigates to equivalent page in selected version

07-breadcrumbs.js (38 lines)

Breadcrumb navigation:

  • Builds breadcrumb trail from page hierarchy

  • Handles click events for navigation

Script Loading Order

  1. head-styles.hbs — inline FOUC prevention script (runs immediately, before CSS loads)

  2. Page renders with correct data-theme attribute

  3. footer-scripts.hbs loads (at end of <body>):

    1. site.js — bundled files 01-07 (synchronous)

    2. domus-ui.js — theme toggle, focus mode, code enhancements (synchronous)

    3. highlight.bundle.js — syntax highlighting (async, non-blocking)

    4. Search scripts (conditional, if SITE_SEARCH_PROVIDER is set)