From d11984ee00c868535c6ae0083270f5669502000d Mon Sep 17 00:00:00 2001
From: erseco <info@ernesto.es>
Date: Sat, 19 Sep 2026 10:07:32 +0100
Subject: [PATCH] Document the vendored libraries and why some stay

The dependencies that matter here are files, not package.json entries, and
until now nothing recorded what they are or why the old ones had not been
replaced. That left every future reader to work it out again, and made
"it is old" look like a sufficient reason to change something.

docs/vendored-libraries.md splits them by what can actually be done with
them: host-provided (jQuery, jQuery UI, FileSaver), maintained upstream
(mousewheel, minicolors), and retained legacy with the reason in each case.
jquery.hotkeys works on jQuery 3.7.1 and both halves of its contract are
covered by tests. dragscrollable has had no release since 2009 and the copy
here is not upstream's -- David Richard added delegateMode in 2011 -- so it
is application source carrying a third-party header, not an upgradable
dependency. The Aristo-derived stylesheet is the editor's appearance, and
app.css carries the rules that adapt it to jQuery UI 1.14 markup.

docs/jquery-tmpl-replacement.md is the one that needs evidence rather than a
verdict, because it crosses repositories: the implementation is bundled here
and the seven templates live in eXeLearning's editor page. It lists the eight
call sites, the templates, and the three syntax features actually used out of
everything the library offers -- four call sites pass no data at all. It also
notes that #template-export-map is referenced but not present in
eXeLearning's page, and that #template-open-table-item, the only one
rendering a list, is the piece without test coverage and the place to start.
---
 docs/jquery-tmpl-replacement.md | 80 ++++++++++++++++++++++++++++
 docs/vendored-libraries.md      | 93 +++++++++++++++++++++++++++++++++
 2 files changed, 173 insertions(+)
 create mode 100644 docs/jquery-tmpl-replacement.md
 create mode 100644 docs/vendored-libraries.md

diff --git a/docs/jquery-tmpl-replacement.md b/docs/jquery-tmpl-replacement.md
new file mode 100644
index 00000000..126bbb8b
--- /dev/null
+++ b/docs/jquery-tmpl-replacement.md
@@ -0,0 +1,80 @@
+# Replacing jquery.tmpl — scope note
+
+`jquery.tmpl` was abandoned in 2011 while still labelled `1.0.0pre`. It works on jQuery
+3.7.1 and everything built with it is covered by browser tests, so there is no urgency.
+This note exists so that replacing it can be decided on evidence rather than estimated
+from scratch later.
+
+**It is not a dependency bump.** The implementation is bundled by this repository; the
+templates it renders live in eXeLearning, in
+`public/libs/tinymce_5/js/tinymce/plugins/exemindmap/editor/index.html`. Replacing it
+means changing both repositories together, and the fork cannot do it alone.
+
+## Call sites
+
+Eight, all of the form `$("#template-x").tmpl(data)`:
+
+| File | Template | Data |
+|---|---|---|
+| `FloatPanel.js` | `#template-float-panel` | `{ title }` |
+| `Inspector.js` | `#template-inspector` | none |
+| `Navigator.js` | `#template-navigator` | none |
+| `Notification.js` | `#template-notification` | the notification options |
+| `ExportMap.js` | `#template-export-map` | none |
+| `SaveDocument.js` | `#template-save` | none |
+| `OpenDocument.js` | `#template-open` | none |
+| `OpenDocument.js` | `#template-open-table-item` | an array of documents, plus `$item.format` |
+
+Four of the eight render a template with no data at all — those are static markup in a
+`<script>` tag and need no template engine whatsoever.
+
+## Templates
+
+Seven, all in eXeLearning's `editor/index.html`:
+
+```
+template-float-panel   template-inspector   template-navigator   template-notification
+template-open          template-open-table-item                  template-save
+```
+
+`#template-export-map` is referenced by `ExportMap.js` but is **not** among them: that
+command is not wired into eXeLearning's toolbar, so the call site is unreachable there.
+Worth confirming before relying on it.
+
+## Syntax actually used
+
+Far less than the library offers:
+
+| Feature | Uses | Replacement |
+|---|---|---|
+| `${...}` | 13 | ordinary interpolation |
+| `{{if}}` | 2 | a conditional |
+| `{{html}}` | 2 | assignment to `innerHTML`, with the same escaping question as today |
+
+No `{{each}}`, `{{tmpl}}`, `{{wrap}}`, or nested templates. `$item.format` appears once,
+in the open-dialog table row, and is a formatting helper passed as an option.
+
+## Could native APIs replace it?
+
+Yes, in principle. `<template>` plus `cloneNode` covers the static four outright. The
+three that take data need interpolation — either a small helper (a `${...}` replacer
+over a data object is a few lines) or converting those templates to `<template>` markup
+whose fields are filled by direct DOM assignment, which is what the values are used for
+anyway.
+
+The honest catch is not the engine, it is the boundary. The templates are eXeLearning's
+file and the renderer is this repository's bundle, so any replacement lands as a
+coordinated pair of changes with a version of each in flight at once — and the vendored
+bundle is pinned by hash, so the two must be merged in a known order.
+
+## Scope and tests
+
+Small in code, awkward in coordination: roughly a day, most of it verification rather
+than typing.
+
+The existing browser tests already assert that the panels and dialogs render with
+substituted text and no leftover `${` placeholder, which is the contract a replacement
+has to meet. What they do not yet cover is `#template-open-table-item` — the only
+template that renders a list, uses `$item`, and is therefore the one most likely to
+behave differently. **Cover that first**; it is the piece that would otherwise be
+verified by hand.
diff --git a/docs/vendored-libraries.md b/docs/vendored-libraries.md
new file mode 100644
index 00000000..e5552934
--- /dev/null
+++ b/docs/vendored-libraries.md
@@ -0,0 +1,93 @@
+# Vendored libraries
+
+mindmaps predates package managers for browser code, so its dependencies are files in
+the repository rather than entries in `package.json`. This records what each one is,
+where it came from, and — for the ones that are no longer maintained anywhere — why it
+is still here rather than replaced.
+
+Being old is not by itself a reason to replace a library. A vendored file that works,
+has a known provenance and is covered by tests is a smaller risk than a migration
+nobody asked for. The entries below are split on that basis.
+
+## Host-provided
+
+Loaded by the page and deliberately **not** concatenated into the bundle, so an
+application embedding mindmaps supplies its own. They live in `src/js/vendor/` because
+the build does not copy `src/js/libs/` into `dist` — everything there is already inside
+the bundle.
+
+| Library | Version | Licence | Notes |
+|---|---|---|---|
+| jQuery | 3.7.1 | MIT | Byte-identical to `jquery@3.7.1` on npm and to the copy eXeLearning ships |
+| jQuery UI | 1.14.1 | MIT | Byte-identical to `jquery-ui@1.14.1` on npm and to eXeLearning's copy |
+| FileSaver.js | 2.0.5 | MIT | Consumed by `SaveDocument.js` via `window.saveAs` |
+
+## Maintained upstream, vendored here
+
+Still released, tracked by version, updated as part of normal maintenance.
+
+| Library | Version | Licence | Provenance |
+|---|---|---|---|
+| jquery.mousewheel | 3.2.2 | MIT | `jquery/jquery-mousewheel` tag `3.2.2`; npm tarball and git tag compared and identical |
+| jquery.minicolors | 2.3.6 | MIT | `@claviska/jquery-minicolors@2.3.6` — the scoped package; the unscoped one is stale and not the author's |
+
+## Retained legacy code
+
+No maintained upstream to move to. Kept as vendored source with explicit provenance,
+not pretended to be a current dependency.
+
+### jquery.hotkeys 0.8
+
+*John Resig, dual MIT/GPL, based on work by Tzury Bar Yochay.*
+
+**Used once.** `ShortcutController.js` passes a shortcut string as `bind()`'s event
+data:
+
+```js
+$(document).bind(type, shortcut, function(e) { ... });
+```
+
+The plugin reads that string, matches modifiers against the key event, and declines to
+fire while a `textarea`, `select` or text input has focus — which is what keeps typing
+a caption from triggering the delete command.
+
+**Retained because it works.** It runs correctly on jQuery 3.7.1 and the browser tests
+cover both halves of its contract: `ctrl+z` undoes exactly once, and a shortcut key
+typed into a caption does not fire the command. Replacing a working 80-line file that
+is covered by tests, purely because it is old, would trade a known quantity for an
+unknown one. If it is ever replaced, `KeyboardEvent.key` plus a small matcher would do
+the job — but that is a change to make deliberately, with those tests as the contract.
+
+### dragscrollable 1.0
+
+*Miquel Herrera (2009), dual MIT/GPL — **with a local modification**.*
+
+**Used once**, in `CanvasView.js`, to pan the canvas by dragging its background.
+
+**This is not an upgradable dependency.** There has been no upstream release since
+2009, and the copy here is not upstream's: David Richard added a `delegateMode` option
+in 2011 so the handler can be attached by delegation rather than bound directly. Any
+"update" would mean taking a different project and reapplying that change.
+
+Treat it as maintained application source that happens to carry a third-party licence
+header. The panning behaviour is covered by a browser test.
+
+### Aristo-derived stylesheet
+
+*Derived from the Aristo jQuery UI theme, itself built for jQuery UI 1.8.7.*
+
+**This is the editor's appearance**, not a drop-in theme that can be swapped for a
+current one. It is maintained application CSS: `app.css` carries the rules that adapt
+it to jQuery UI 1.14 markup — laying controlgroups out inline where buttonsets used to
+be, and supplying the `.ui-front` stacking rule the theme predates, without which modal
+dialogs sit underneath their own overlay.
+
+Replacing it belongs to a visual redesign with screenshot coverage, not to dependency
+maintenance.
+
+### jquery.tmpl 1.0.0pre
+
+*Software Freedom Conservancy, MIT. Abandoned in 2011 while still in beta.*
+
+Retained, but unlike the others this one is a genuine architectural question rather
+than a judgement call. See [jquery-tmpl-replacement.md](jquery-tmpl-replacement.md).