hdoc-tools 0.62.4 → 0.63.0

package/ui/js/hb.vue.js

@@ -0,0 +1,121 @@
+//--
+//-- Vue 3 app factory for the docs site.
+//--
+//-- Vue 3 removed the three things this site was originally built on:
+//--   * `new Vue({el:...})`            -> Vue.createApp(options).mount(el)
+//--   * Vue.component(name,def)        -> app.component(name,def)   (per app, not global)
+//--   * Vue.filter(name,fn) + {{x|f}}  -> gone entirely
+//--
+//-- That is awkward here because there is no build step, several independent scripts register
+//-- shared components (js/webcomponents/*, js/doc.hornbill.js, settings/js/*), and the page
+//-- creates more than one app: the shell, plus a short-lived app for every injected article
+//-- and every settings view. With no single place that owns "the app", per-app registration
+//-- would mean every script needing a handle to every app.
+//--
+//-- So hbVue keeps a small registry that scripts can add to before any app exists, and
+//-- hbCreateApp stamps the whole registry onto each app it builds. One-for-one replacements:
+//--
+//--   Vue.component(n,d)   -> hbVue.component(n,d)
+//--   Vue.filter(n,f)      -> hbVue.helper(n,f)  and {{x | f}} becomes {{f(x)}} in templates
+//--   new Vue({el:e,...})  -> hbMount({...}, e)      (returns the same vm you used before)
+//--   vm.$destroy()        -> hbVue.unmount(vm)
+//--
+//-- Load this immediately after Vue and before any script that registers or mounts. //-- SG
+
+var hbVue = {
+    //-- name -> component definition, applied to every app created by hbCreateApp
+    components: {},
+
+    //-- name -> function, exposed to every template as a callable (the Vue.filter replacement)
+    helpers: {},
+
+    //-- native custom elements that may appear inside a compiled template. Vue 3 treats an
+    //-- unknown hyphenated tag as a component and logs "Failed to resolve component", so any
+    //-- real custom element has to be declared. Doc content is compiled under v-pre and is
+    //-- therefore already exempt - this is for elements in the app templates themselves.
+    customElements: ["api-param-optional"],
+
+    //-- vm proxy -> app, so a caller holding a vm can still tear it down (see unmount)
+    _apps: new WeakMap(),
+
+    component: function (name, definition) {
+        hbVue.components[name] = definition;
+        return hbVue;
+    },
+
+    helper: function (name, fn) {
+        hbVue.helpers[name] = fn;
+        return hbVue;
+    },
+
+    //-- tear down an app given the vm that hbMount returned. Vue 3 has no vm.$destroy();
+    //-- teardown is an app-level operation, and app.unmount() also empties the container.
+    unmount: function (vm) {
+        if (!vm) return false;
+        let app = hbVue._apps.get(vm);
+        if (!app) return false;
+        app.unmount();
+        hbVue._apps.delete(vm);
+        return true;
+    }
+};
+
+//-- create an app with the shared registry applied, but do not mount it. Use this when you
+//-- need the app handle itself; otherwise use hbMount.
+function hbCreateApp(options) {
+    let app = Vue.createApp(options);
+
+    //-- keep Vue from trying to resolve declared custom elements as components
+    app.config.compilerOptions.isCustomElement = function (tag) {
+        return hbVue.customElements.indexOf(tag) !== -1;
+    };
+
+    //-- template helpers land on globalProperties so templates can call them directly
+    for (let name in hbVue.helpers) {
+        if (hbVue.helpers.hasOwnProperty(name)) {
+            app.config.globalProperties[name] = hbVue.helpers[name];
+        }
+    }
+
+    for (let name in hbVue.components) {
+        if (hbVue.components.hasOwnProperty(name)) {
+            app.component(name, hbVue.components[name]);
+        }
+    }
+
+    return app;
+}
+
+//-- create and mount in one call. Returns the mounted root instance proxy - the same object
+//-- `new Vue({el})` used to return, so vm.someMethod(), vm.someDataProp, vm.$forceUpdate()
+//-- and vm.$nextTick() all still work.
+//--
+//-- NOTE the one behaviour change from Vue 2: Vue 2 compiled the mount element's *outerHTML*,
+//-- so directives on the element itself (v-on:click, :class) were live. Vue 3 compiles its
+//-- *innerHTML* and leaves the container alone, so any directive on the container is silently
+//-- ignored. Bind those by hand after mounting (see hbBindRootHandler).
+function hbMount(options, elementOrSelector) {
+    let app = hbCreateApp(options);
+    let vm = app.mount(elementOrSelector);
+    hbVue._apps.set(vm, app);
+    return vm;
+}
+
+//-- Vue 3 does not compile directives on the mount container, so a `v-on:<event>` that used to
+//-- sit on the root element has to be wired up manually. Markup declares it as
+//-- data-root-<event>="<methodName>" and this attaches it, which keeps the intent visible in
+//-- the HTML rather than burying it in a script. No attribute means no handler, which is how
+//-- _inline.html opts out while sharing the same controller as index.html.
+function hbBindRootHandler(vm, elementOrSelector, eventName) {
+    let el = (typeof elementOrSelector === "string") ? document.querySelector(elementOrSelector) : elementOrSelector;
+    if (!el || !vm) return false;
+
+    let methodName = el.getAttribute("data-root-" + eventName);
+    if (!methodName || typeof vm[methodName] !== "function") return false;
+
+    el.addEventListener(eventName, function (ev) {
+        vm[methodName](ev);
+    });
+
+    return true;
+}