88 lines
2.5 KiB
Markdown
88 lines
2.5 KiB
Markdown
# Module Conventions
|
|
|
|
Ped-AI currently uses mixed JavaScript module styles. This is intentional during incremental modernization.
|
|
|
|
## Current Convention
|
|
|
|
| Area | Module Style | Notes |
|
|
|---|---|---|
|
|
| Backend `server.js`, `src/**` | CommonJS | Use `require` and `module.exports` for now |
|
|
| New frontend modules | ESM | Use `import` and `export` |
|
|
| Older frontend files | Classic browser globals | Convert only when touching the feature intentionally |
|
|
| Dual browser/test files | Case-by-case | Keep classic style only when tests or browser globals require it |
|
|
|
|
Do not add root-level `"type": "module"` without a full backend migration plan. It would change how every `.js` file is interpreted by Node.
|
|
|
|
## CommonJS Example
|
|
|
|
```js
|
|
var express = require('express');
|
|
var router = express.Router();
|
|
|
|
module.exports = router;
|
|
```
|
|
|
|
## ESM Example
|
|
|
|
```js
|
|
import { escapeHtml } from './assistant/citations.js';
|
|
|
|
export function renderSourcesList(sources) {
|
|
return '';
|
|
}
|
|
```
|
|
|
|
## Frontend Modernization Path
|
|
|
|
1. New frontend code should be ESM where possible.
|
|
2. Existing globals can remain until that feature is refactored.
|
|
3. Keep browser script load order stable while refactoring.
|
|
4. Export pure helper functions so Node tests can import them.
|
|
5. Use `CustomEvent` or explicit imports instead of adding new global APIs when practical.
|
|
|
|
## Acceptable Globals
|
|
|
|
Globals are acceptable when they are part of the current shell contract.
|
|
|
|
Examples:
|
|
|
|
- `window.activateTab`,
|
|
- `window.getAuthHeaders`,
|
|
- shared UI helpers still consumed by legacy feature files.
|
|
|
|
Do not add new globals when an import or event would be clearer.
|
|
|
|
## Rendering And `innerHTML`
|
|
|
|
`innerHTML` is allowed only when one of these is true:
|
|
|
|
- the HTML is a static template controlled by the app,
|
|
- all dynamic values are escaped before insertion,
|
|
- the HTML has passed through the approved sanitizer,
|
|
- the content is a trusted app component fetched from `public/components/`.
|
|
|
|
Prefer `textContent` for plain text.
|
|
|
|
Unsafe:
|
|
|
|
```js
|
|
el.innerHTML = userText;
|
|
el.innerHTML = modelOutput;
|
|
```
|
|
|
|
Safer:
|
|
|
|
```js
|
|
el.textContent = userText;
|
|
el.innerHTML = escapeHtml(userText).replace(/\n/g, '<br>');
|
|
el.innerHTML = sanitizeHtml(renderMarkdown(modelOutput));
|
|
```
|
|
|
|
## Test Expectations
|
|
|
|
When converting a frontend file to ESM, add or update tests for:
|
|
|
|
- exported helper functions,
|
|
- expected globals still present if legacy code needs them,
|
|
- no browser-native `prompt`, `alert`, or `confirm`,
|
|
- no unescaped dynamic text inserted through `innerHTML`.
|