# Function Definitions Reference

## Scope
This file catalogs key PHP and JavaScript functions used by routing, rendering, and UI runtime behavior.

## How To Use This File
1. Use this file for quick lookup before changing behavior.
2. Update function entries when signatures or responsibilities change.
3. Pair with [docs/ARCHITECTURE.md](ARCHITECTURE.md) for flow-level context.

## PHP Functions

### templ.php
1. `isAjaxRequest(): bool`
   - Detects AJAX mode via `X-Requested-With` header or `ajax` query parameter.
2. `resolveContentFile(string $page): string`
   - Maps route key to whitelisted fragment file path.
   - Returns empty string if route is invalid or target file is missing.
3. `renderErrorFragment(string $title, string $msg): string`
   - Returns standard HTML fragment for request errors.

### sidebar.php
1. `navLink(string $page, string $label, string $icon, ?array $badge = null): string`
   - Renders one sidebar nav item with active-state and optional badge.

### mainContent.php (inline JS)
1. `simulateExport(): void`
   - Demo action that shows spinner and success toast.

### content2.php (inline JS)
1. `initChart(): void`
   - Initializes or re-initializes Chart.js traffic chart.
2. `generateReport(): void`
   - Demo action that shows spinner and report toast.

## JavaScript Functions And Modules (`assets/app.js`)

### ProgressBar Module
1. `set(pct)`
2. `start()`
3. `finish()`
4. `fail()`

Behavior:
1. Manages top loading bar width, completion state, and failure style.

### Spinner Module
1. `show(msg = "Loading…")`
2. `hide()`
3. `showDelayed(msg = "Loading…")`
4. `cancelDelayed()`

Behavior:
1. Manages spinner overlay visibility and delayed display.

### Toast Module
1. `show(message, type = "info", duration = TOAST_DURATION)`

Behavior:
1. Renders dismissible toast and auto-removes after duration.

### Navigation Runtime
1. `loadContent(page, pushState = true, label = "")`
2. `window.App.navigate(page, label)`

Behavior:
1. Fetches fragment HTML and updates content, history, title, breadcrumb, and active nav.

### Internal Helpers
1. `_setActiveNav(page)`
2. `_updateScrollBtns()`
3. `_initDynamicContent(container)`
4. `_capitalise(str)`
5. `_escapeHtml(str)`
6. `_buildErrorHTML(page, msg)`

## Update Checklist
- [ ] New public function added to this file.
- [ ] Signature changes reflected here.
- [ ] Removed or renamed functions removed here.