@yuneta/gobj-ui 3.0.0 → 4.0.0

package/src/yui_tabulator_i18n.js

@@ -0,0 +1,128 @@
+/***********************************************************************
+ *          yui_tabulator_i18n.js
+ *
+ *      The strings TABULATOR renders on its own — the paginator ("Page
+ *      Size", "First", "Prev", "Next", "Last"), the placeholder ("No Data
+ *      Available"), the loading/error notices — through the app's i18n.
+ *
+ *      They are not built by any gclass, so nothing here or in an app ever
+ *      passed them through t(): a table sat in English inside an otherwise
+ *      Spanish view, and a language switch did not touch it.
+ *
+ *      Two calls:
+ *
+ *          new Tabulator($el, {..., ...yui_tabulator_lang(t)});
+ *          yui_tabulator_relocalize(table, t);   // on a language change
+ *
+ *      Every key carries an English `defaultValue`, so an app that does not
+ *      define it renders exactly what Tabulator rendered before — the
+ *      keys are an OPPORTUNITY to translate, never a requirement.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import {log_warning} from "@yuneta/gobj-js";
+
+
+/*  Tabulator re-renders the parts it owns only when the locale NAME changes:
+ *  setLocale() with the name already in force is a no-op, so re-registering
+ *  fresh strings under "default" left the paginator in the old language. Each
+ *  application of a language therefore gets its own name.  */
+let __lang_seq__ = 0;
+
+function next_lang_name()
+{
+    return `yui-${++__lang_seq__}`;
+}
+
+/***************************************************************
+ *  Tabulator's own strings, in the CURRENT language.
+ *
+ *  ONE lang dict (not one per locale): the app owns the locales and hands us
+ *  only its live `t`, so a language change rebuilds the dict and re-applies
+ *  it under a fresh name (yui_tabulator_relocalize).
+ ***************************************************************/
+function yui_tabulator_lang(t)
+{
+    let name = next_lang_name();
+    let langs = {};
+    langs[name] = tabulator_strings(t);
+    return {
+        locale: name,
+        langs:  langs
+    };
+}
+
+function tabulator_strings(t)
+{
+    let tr = (key, def) => t(key, {defaultValue: def});
+
+    return {
+        data: {
+            loading: tr("loading", "Loading"),
+            error:   tr("error", "Error")
+        },
+        pagination: {
+            page_size:   tr("page size", "Page Size"),
+            page_title:  tr("show page", "Show Page"),
+            first:       tr("first", "First"),
+            first_title: tr("first page", "First Page"),
+            last:        tr("last", "Last"),
+            last_title:  tr("last page", "Last Page"),
+            prev:        tr("prev", "Prev"),
+            prev_title:  tr("prev page", "Prev Page"),
+            next:        tr("next", "Next"),
+            next_title:  tr("next page", "Next Page"),
+            all:         tr("all", "All")
+        },
+        headerFilters: {
+            default: tr("filter column", "filter column...")
+        }
+    };
+}
+
+/***************************************************************
+ *  Put an EXISTING table in the current language: rebuild the strings and
+ *  re-apply the locale, which is what makes Tabulator re-render the parts
+ *  it owns (the paginator above all — it is drawn once, at build).
+ *
+ *  Silent no-op on a table that is gone: a language switch races nothing,
+ *  but a view torn down mid-switch must not log a failure it cannot act on.
+ ***************************************************************/
+function yui_tabulator_relocalize(table, t)
+{
+    if(!table) {
+        return;
+    }
+    try {
+        let name = next_lang_name();
+        let strings = tabulator_strings(t);
+
+        /*  Tabulator DEEP-CLONES options.langs into its localize module when
+         *  the table is built, and never looks at the option again: writing a
+         *  new language there and calling setLocale() only earned a
+         *  "Matching locale not found, using default: yui-5" — and the
+         *  paginator it was meant to translate stayed in the old language.
+         *  Install it where the module actually reads it. The option is still
+         *  written, so a table rebuilt from its options keeps the language.  */
+        table.options.langs = table.options.langs || {};
+        table.options.langs[name] = strings;
+
+        let localize = table.modules && table.modules.localize;
+        if(localize && typeof localize.installLang === "function") {
+            localize.installLang(name, strings);
+        } else {
+            log_warning(`yui_tabulator_relocalize: no localize module: ` +
+                        `Tabulator's own chrome stays in the old language`);
+        }
+
+        table.setLocale(name);      /*  a NEW name: this is what re-renders  */
+    } catch(e) {
+        log_warning(`yui_tabulator_relocalize: table gone: ${e}`);
+    }
+}
+
+export {
+    yui_tabulator_lang,
+    yui_tabulator_relocalize,
+};

package/src/yui_theme.js

@@ -0,0 +1,147 @@
+/***********************************************************************
+ *          yui_theme.js
+ *
+ *      The app's light/dark theme, and how a gclass follows it.
+ *
+ *      The theme lives in ONE place: the `data-theme` attribute of
+ *      <html> (the Bulma convention, set by the shell's theme toggle).
+ *      Reading it is the only way to know the current theme; there is
+ *      no service to ask.
+ *
+ *      Components used to ask a legacy C_YUI_MAIN "__yui_main__"
+ *      service instead — read its `theme` attr, subscribe to its
+ *      EV_THEME. That path was retired: nothing ever WROTE that attr,
+ *      so it answered "light" for the life of the app, and no shell
+ *      published EV_THEME. C_YUI_SHELL has no such service at all.
+ *
+ *      A theme change is a DOM mutation — an OS notification — so it
+ *      enters the machine as an event: yui_watch_theme() translates
+ *      the mutation into EV_THEME and the gclass's action does the
+ *      restyling. Nothing happens in the observer callback itself.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import {
+    gobj_send_event,
+    gobj_is_destroying,
+} from "@yuneta/gobj-js";
+
+
+/************************************************************
+ *   The active theme: "dark" | "light".
+ *
+ *   <html data-theme> when the app sets it, else the OS
+ *   preference, else light.
+ ************************************************************/
+function yui_theme_now()
+{
+    if(typeof document === "undefined") {
+        return "light";
+    }
+    let attr = document.documentElement.getAttribute("data-theme");
+    if(attr === "dark" || attr === "light") {
+        return attr;
+    }
+    if(typeof window !== "undefined" && window.matchMedia) {
+        return window.matchMedia("(prefers-color-scheme: dark)").matches
+            ? "dark" : "light";
+    }
+    return "light";
+}
+
+/************************************************************
+ *   True when the app renders dark.
+ ************************************************************/
+function yui_is_dark()
+{
+    return yui_theme_now() === "dark";
+}
+
+/************************************************************
+ *   Follow the theme: watch <html data-theme> and send `event`
+ *   (default EV_THEME, kw {theme}) to `gobj` on every change,
+ *   so the gclass restyles in its ACTION — the observer only
+ *   translates the notification.
+ *
+ *   The gclass must declare `event` in its FSM, and must
+ *   disconnect the returned observer in mt_destroy:
+ *
+ *       priv.theme_observer = yui_watch_theme(gobj);
+ *       ...
+ *       if(priv.theme_observer) {
+ *           priv.theme_observer.disconnect();
+ *           priv.theme_observer = null;
+ *       }
+ *
+ *   Watches BOTH sources: <html data-theme> (a MutationObserver)
+ *   and the OS preference (matchMedia prefers-color-scheme, which
+ *   is the live source while the attribute is absent — the
+ *   "system" theme).
+ *
+ *   Returns a handle with disconnect(), or null where there is
+ *   no DOM.
+ ************************************************************/
+function yui_watch_theme(gobj, event = "EV_THEME")
+{
+    if(typeof MutationObserver === "undefined" || typeof document === "undefined") {
+        return null;
+    }
+
+    let $html = document.documentElement;
+    let last = yui_theme_now();
+
+    let notify = function() {
+        let theme = yui_theme_now();
+        /*  data-theme can be rewritten with the same value (a re-render,
+         *  another observer); only a real change is an event. */
+        if(theme === last) {
+            return;
+        }
+        last = theme;
+        if(gobj_is_destroying(gobj)) {
+            return;
+        }
+        gobj_send_event(gobj, event, {theme: theme}, gobj);
+    };
+
+    let mo = new MutationObserver(notify);
+    mo.observe($html, {attributes: true, attributeFilter: ["data-theme"]});
+
+    /*  The "system" theme: with data-theme ABSENT, yui_theme_now()
+     *  answers from the OS preference (and Bulma follows it via
+     *  prefers-color-scheme), so an OS auto-switch (sunset) IS a theme
+     *  change — without this listener the CSS would flip while every
+     *  canvas kept its old palette, the exact bug class the attribute
+     *  observer kills.  notify() dedupes, so when the app pins
+     *  data-theme this listener never fires an event (the attribute
+     *  wins inside yui_theme_now). */
+    let mql = null;
+    if(typeof window !== "undefined" && window.matchMedia) {
+        mql = window.matchMedia("(prefers-color-scheme: dark)");
+        if(typeof mql.addEventListener === "function") {
+            mql.addEventListener("change", notify);
+        } else {
+            mql = null;
+        }
+    }
+
+    /*  One handle, one disconnect() — same contract as a bare
+     *  MutationObserver, covering both sources. */
+    return {
+        disconnect: function() {
+            mo.disconnect();
+            if(mql) {
+                mql.removeEventListener("change", notify);
+                mql = null;
+            }
+        }
+    };
+}
+
+
+export {
+    yui_theme_now,
+    yui_is_dark,
+    yui_watch_theme,
+};