@yuneta/gobj-ui 1.0.1 → 2.2.0

package/src/shell_toolbar_helpers.js

@@ -0,0 +1,221 @@
+/***********************************************************************
+ *          shell_toolbar_helpers.js
+ *
+ *      Pure helpers for the C_YUI_SHELL declarative toolbar.  Split out
+ *      of c_yui_shell.js so the additive item types ("brand", "avatar")
+ *      and the new "dropdown" action type can be unit-tested without a
+ *      DOM.
+ *
+ *      Three responsibilities:
+ *          - classify_toolbar_item()  — pick the renderer kind
+ *          - validate_toolbar_item()  — shape check, returns warnings
+ *          - validate_dropdown_action() — shape check for dropdowns
+ *
+ *      Item kinds:
+ *          "brand"   — logo (img) + wordmark (text); default action navigate
+ *          "avatar"  — circular initials, populated by an app-registered
+ *                      provider callback (yui_shell_set_avatar_provider)
+ *          "action"  — every other toolbar item: icon and/or label that
+ *                      triggers an action.type on click
+ *
+ *      Action types accepted on a toolbar item or on a dropdown sub-item:
+ *          "navigate" | "drawer" | "event" | "dropdown"
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+export const TOOLBAR_ITEM_KINDS = ["brand", "avatar", "connection", "action"];
+export const TOOLBAR_ACTION_TYPES = ["navigate", "drawer", "event", "dropdown"];
+
+
+/************************************************************
+ *  Decide which renderer to use for a toolbar item.
+ *
+ *  Returns one of "brand" | "avatar" | "action".  Items with
+ *  no `type` (legacy contract) classify as "action" so existing
+ *  configs keep working unchanged.
+ ************************************************************/
+export function classify_toolbar_item(item)
+{
+    if(!item || typeof item !== "object") {
+        return "action";
+    }
+    let t = item.type;
+    if(t === "brand" || t === "avatar" || t === "connection") {
+        return t;
+    }
+    return "action";
+}
+
+
+/************************************************************
+ *  Validate one toolbar item.  Returns { ok, warnings }.
+ *
+ *  Lenient by design: unknown fields are ignored so apps can
+ *  carry extra metadata.  We only flag shapes that would render
+ *  visibly broken (brand without logo/wordmark, dropdown without
+ *  items, unknown action.type, etc.).
+ ************************************************************/
+export function validate_toolbar_item(item)
+{
+    let warnings = [];
+    if(!item || typeof item !== "object") {
+        warnings.push("toolbar item must be an object");
+        return { ok: false, warnings: warnings };
+    }
+
+    let kind = classify_toolbar_item(item);
+    let id = item.id || "<no-id>";
+
+    if(kind === "brand") {
+        if(!_is_non_empty_string(item.logo)) {
+            warnings.push(
+                `toolbar item '${id}' (type:brand) requires 'logo' (image URL)`
+            );
+        }
+        if(!_is_non_empty_string(item.wordmark)) {
+            warnings.push(
+                `toolbar item '${id}' (type:brand) requires 'wordmark' (text)`
+            );
+        }
+    }
+
+    /*  avatar has no required fields beyond the optional action — the
+     *  initials come from a runtime provider, not the JSON. */
+
+    /*  Validate the action shape, including the new "dropdown" type. */
+    if(item.action !== undefined && item.action !== null) {
+        let nested = validate_action(item.action, id);
+        for(let w of nested) {
+            warnings.push(w);
+        }
+    }
+
+    /*  Optional secondary (right-click) action — same shape as action,
+     *  used e.g. by a connection indicator to open a dev panel. */
+    if(item.context_action !== undefined && item.context_action !== null) {
+        let nested = validate_action(item.context_action, id);
+        for(let w of nested) {
+            warnings.push(w);
+        }
+    }
+
+    return { ok: warnings.length === 0, warnings: warnings };
+}
+
+
+/************************************************************
+ *  Validate an `action` object (toolbar item action or
+ *  dropdown sub-item action).  Returns an array of warnings.
+ ************************************************************/
+export function validate_action(action, owner_id)
+{
+    let warnings = [];
+    if(!action || typeof action !== "object") {
+        return warnings;
+    }
+    let id = owner_id || "<no-id>";
+
+    if(action.type === undefined || action.type === null) {
+        /*  No type at all is also caught at runtime by handle_toolbar_action,
+         *  but flag it here so config errors surface during validate_config. */
+        warnings.push(`toolbar item '${id}' has action without 'type'`);
+        return warnings;
+    }
+    if(TOOLBAR_ACTION_TYPES.indexOf(action.type) < 0) {
+        warnings.push(
+            `toolbar item '${id}' has unknown action.type '${action.type}'; ` +
+            `valid: ${TOOLBAR_ACTION_TYPES.join(", ")}`
+        );
+        return warnings;
+    }
+
+    if(action.type === "navigate" && !_is_non_empty_string(action.route)) {
+        warnings.push(
+            `toolbar item '${id}' (action.type:navigate) requires 'route'`
+        );
+    }
+    if(action.type === "event" && !_is_non_empty_string(action.event)) {
+        warnings.push(
+            `toolbar item '${id}' (action.type:event) requires 'event' name`
+        );
+    }
+    if(action.type === "dropdown") {
+        let nested = validate_dropdown_action(action, id);
+        for(let w of nested) {
+            warnings.push(w);
+        }
+    }
+
+    return warnings;
+}
+
+
+/************************************************************
+ *  Validate the items of a dropdown action.
+ *
+ *  Each entry is either:
+ *      { type: "divider" [, show_on] }
+ *      { id, name?, icon?, action, show_on? }
+ *
+ *  Nested dropdowns are NOT supported: an "action.type": "dropdown"
+ *  inside a dropdown sub-item is flagged.
+ ************************************************************/
+export function validate_dropdown_action(action, owner_id)
+{
+    let warnings = [];
+    let id = owner_id || "<no-id>";
+
+    if(!Array.isArray(action.items)) {
+        warnings.push(
+            `toolbar item '${id}' (action.type:dropdown) requires items[]`
+        );
+        return warnings;
+    }
+    if(action.items.length === 0) {
+        warnings.push(
+            `toolbar item '${id}' (action.type:dropdown) has empty items[]`
+        );
+    }
+
+    for(let i = 0; i < action.items.length; i++) {
+        let it = action.items[i];
+        let where = `${id}[${i}]`;
+        if(!it || typeof it !== "object") {
+            warnings.push(`dropdown item ${where} must be an object`);
+            continue;
+        }
+        if(it.type === "divider") {
+            continue;
+        }
+        if(!it.action || typeof it.action !== "object") {
+            warnings.push(
+                `dropdown item ${where} requires an action object`
+            );
+            continue;
+        }
+        if(it.action.type === "dropdown") {
+            warnings.push(
+                `dropdown item ${where} has action.type:dropdown — ` +
+                `nested dropdowns are not supported`
+            );
+            continue;
+        }
+        let nested = validate_action(it.action, where);
+        for(let w of nested) {
+            warnings.push(w);
+        }
+    }
+
+    return warnings;
+}
+
+
+/************************************************************
+ *  Internal — non-empty trimmed string check.
+ ************************************************************/
+function _is_non_empty_string(v)
+{
+    return typeof v === "string" && v.trim().length > 0;
+}

package/src/shell_toolbar_helpers.test.js

@@ -0,0 +1,207 @@
+/***********************************************************************
+ *          shell_toolbar_helpers.test.mjs
+ *
+ *      Unit tests for the pure toolbar helpers used by C_YUI_SHELL.
+ *      Run with: node --test tests/
+ ***********************************************************************/
+import { test, expect } from "vitest";
+import {
+    TOOLBAR_ITEM_KINDS,
+    TOOLBAR_ACTION_TYPES,
+    classify_toolbar_item,
+    validate_toolbar_item,
+    validate_action,
+    validate_dropdown_action,
+} from "./shell_toolbar_helpers.js";
+
+
+/*============================================================
+ *      classify_toolbar_item
+ *============================================================*/
+test("classify: legacy item without 'type' is 'action'", () => {
+    expect(classify_toolbar_item({ id: "home", icon: "yi-home" })).toBe("action");
+});
+
+test("classify: type:'brand' classifies as 'brand'", () => {
+    expect(classify_toolbar_item({ id: "b", type: "brand", logo: "/x.svg", wordmark: "X" })).toBe("brand");
+});
+
+test("classify: type:'avatar' classifies as 'avatar'", () => {
+    expect(classify_toolbar_item({ id: "u", type: "avatar" })).toBe("avatar");
+});
+
+test("classify: type:'connection' classifies as 'connection'", () => {
+    expect(classify_toolbar_item({ id: "conn", type: "connection" })).toBe("connection");
+});
+
+test("validate: bad context_action surfaces a warning", () => {
+    let r = validate_toolbar_item({
+        id: "conn", type: "connection",
+        context_action: { type: "bogus" }
+    });
+    expect(r.ok).toBe(false);
+    expect(r.warnings.some(w => w.includes("unknown action.type"))).toBeTruthy();
+});
+
+test("classify: unknown type falls back to 'action'", () => {
+    expect(classify_toolbar_item({ id: "?", type: "phantom" })).toBe("action");
+});
+
+test("classify: null/undefined are 'action'", () => {
+    expect(classify_toolbar_item(null)).toBe("action");
+    expect(classify_toolbar_item(undefined)).toBe("action");
+});
+
+
+/*============================================================
+ *      validate_toolbar_item — brand
+ *============================================================*/
+test("validate brand: ok with logo + wordmark", () => {
+    let r = validate_toolbar_item({
+        id: "brand", type: "brand",
+        logo: "/wm.svg", wordmark: "Wattyzer",
+        action: { type: "navigate", route: "/welcome" }
+    });
+    expect(r.ok).toBe(true);
+    expect(r.warnings).toEqual([]);
+});
+
+test("validate brand: missing logo flags warning", () => {
+    let r = validate_toolbar_item({
+        id: "brand", type: "brand", wordmark: "X"
+    });
+    expect(r.ok).toBe(false);
+    expect(r.warnings.join("\n")).toMatch(/requires 'logo'/);
+});
+
+test("validate brand: missing wordmark flags warning", () => {
+    let r = validate_toolbar_item({
+        id: "brand", type: "brand", logo: "/x.svg"
+    });
+    expect(r.ok).toBe(false);
+    expect(r.warnings.join("\n")).toMatch(/requires 'wordmark'/);
+});
+
+test("validate brand: empty-string fields count as missing", () => {
+    let r = validate_toolbar_item({
+        id: "brand", type: "brand", logo: "  ", wordmark: ""
+    });
+    expect(r.ok).toBe(false);
+    expect(r.warnings.length).toBe(2);
+});
+
+
+/*============================================================
+ *      validate_toolbar_item — avatar
+ *============================================================*/
+test("validate avatar: ok with no extra fields", () => {
+    let r = validate_toolbar_item({ id: "user", type: "avatar" });
+    expect(r.ok).toBe(true);
+});
+
+test("validate avatar: ok with dropdown action", () => {
+    let r = validate_toolbar_item({
+        id: "user", type: "avatar",
+        action: {
+            type: "dropdown",
+            items: [
+                { id: "p", name: "Profile",
+                  action: { type: "navigate", route: "/me" } }
+            ]
+        }
+    });
+    expect(r.ok).toBe(true);
+});
+
+
+/*============================================================
+ *      validate_action
+ *============================================================*/
+test("action: navigate without route flags warning", () => {
+    let w = validate_action({ type: "navigate" }, "x");
+    expect(w.join("\n")).toMatch(/requires 'route'/);
+});
+
+test("action: event without event name flags warning", () => {
+    let w = validate_action({ type: "event" }, "x");
+    expect(w.join("\n")).toMatch(/requires 'event'/);
+});
+
+test("action: unknown action.type flags warning", () => {
+    let w = validate_action({ type: "teleport" }, "x");
+    expect(w.join("\n")).toMatch(/unknown action\.type/);
+});
+
+test("action: missing type flags warning", () => {
+    let w = validate_action({}, "x");
+    expect(w.join("\n")).toMatch(/action without 'type'/);
+});
+
+test("action: drawer with op only is accepted", () => {
+    let w = validate_action({ type: "drawer", op: "toggle" }, "x");
+    expect(w).toEqual([]);
+});
+
+
+/*============================================================
+ *      validate_dropdown_action
+ *============================================================*/
+test("dropdown: missing items[] flags warning", () => {
+    let w = validate_dropdown_action({ type: "dropdown" }, "user");
+    expect(w.join("\n")).toMatch(/requires items\[\]/);
+});
+
+test("dropdown: empty items[] flags warning", () => {
+    let w = validate_dropdown_action({ type: "dropdown", items: [] }, "user");
+    expect(w.join("\n")).toMatch(/empty items\[\]/);
+});
+
+test("dropdown: dividers are accepted without action", () => {
+    let w = validate_dropdown_action({
+        type: "dropdown",
+        items: [
+            { id: "p", name: "Profile",
+              action: { type: "navigate", route: "/me" } },
+            { type: "divider" },
+            { id: "out", name: "Logout",
+              action: { type: "event", event: "EV_LOGOUT" } }
+        ]
+    }, "user");
+    expect(w).toEqual([]);
+});
+
+test("dropdown: sub-item without action flags warning", () => {
+    let w = validate_dropdown_action({
+        type: "dropdown",
+        items: [{ id: "x", name: "X" }]
+    }, "user");
+    expect(w.join("\n")).toMatch(/requires an action object/);
+});
+
+test("dropdown: nested dropdowns rejected", () => {
+    let w = validate_dropdown_action({
+        type: "dropdown",
+        items: [{
+            id: "x", name: "X",
+            action: { type: "dropdown", items: [] }
+        }]
+    }, "user");
+    expect(w.join("\n")).toMatch(/nested dropdowns are not supported/);
+});
+
+test("dropdown: invalid sub-action surfaces underlying warning", () => {
+    let w = validate_dropdown_action({
+        type: "dropdown",
+        items: [{ id: "x", name: "X", action: { type: "navigate" } }]
+    }, "user");
+    expect(w.join("\n")).toMatch(/requires 'route'/);
+});
+
+
+/*============================================================
+ *      Constants exported are stable
+ *============================================================*/
+test("kinds + action-type constants are exposed", () => {
+    expect(TOOLBAR_ITEM_KINDS).toEqual(["brand", "avatar", "connection", "action"]);
+    expect(TOOLBAR_ACTION_TYPES).toEqual(["navigate", "drawer", "event", "dropdown"]);
+});

package/src/tabulator.css

@@ -0,0 +1,53 @@
+/***********************************************************************
+ *          tabulator.css
+ *
+ *          Cross-app Tabulator theme fixes and reusable helpers.
+ *
+ *          Tabulator is a first-class element across the yunos, so its
+ *          styling belongs to the library — not duplicated per app.
+ *          Import this once (after `tabulator.min.css` +
+ *          `tabulator_bulma.css`) so every consumer gets the same
+ *          theme-aware behaviour.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/* ====================================================================
+ *  Active / selected row highlight.
+ *  Green wash + left accent, theme-aware, with enough specificity
+ *  (three classes) to beat the striped-row !important backgrounds.
+ *  Add `yui-row-active` to a `.tabulator-row` element to mark it.
+ * ==================================================================== */
+.tabulator-row.yui-row-active,
+.tabulator-row.yui-row-active.tabulator-row-odd,
+.tabulator-row.yui-row-active.tabulator-row-even {
+    background-color: #E8F6EE !important;
+    box-shadow: inset 4px 0 0 #2BB673;
+}
+
+[data-theme=dark] .tabulator-row.yui-row-active,
+[data-theme=dark] .tabulator-row.yui-row-active.tabulator-row-odd,
+[data-theme=dark] .tabulator-row.yui-row-active.tabulator-row-even {
+    background-color: rgba(43, 182, 115, 0.22) !important;
+    box-shadow: inset 4px 0 0 #2BB673;
+}
+
+/* ====================================================================
+ *  Tree expand/collapse control (the +/- box) in dark theme.
+ *  Tabulator hardcodes the box border and the +/- strokes to #333 on
+ *  a near-black wash — a dark glyph in a dark box on a dark background,
+ *  effectively invisible. Repaint border, wash and strokes light.
+ * ==================================================================== */
+[data-theme=dark] .tabulator-data-tree-control {
+    background: rgba(255, 255, 255, 0.14) !important;
+    border-color: rgba(255, 255, 255, 0.85) !important;
+}
+[data-theme=dark] .tabulator-data-tree-control:hover {
+    background: rgba(255, 255, 255, 0.28) !important;
+}
+[data-theme=dark] .tabulator-data-tree-control .tabulator-data-tree-control-expand,
+[data-theme=dark] .tabulator-data-tree-control .tabulator-data-tree-control-expand:after,
+[data-theme=dark] .tabulator-data-tree-control .tabulator-data-tree-control-collapse:after {
+    background: #ffffff !important;
+}

package/src/wizard_helpers.js

@@ -0,0 +1,117 @@
+/***********************************************************************
+ *          wizard_helpers.js
+ *
+ *      Pure (DOM-free) step logic for C_YUI_WIZARD.
+ *      Kept apart so it is unit-testable with `node --test`
+ *      (same split as shell_toolbar_helpers.js / pager_helpers.js).
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/***************************************************************
+ *  A step is a plain object: { id, title } (content/gobj are
+ *  tracked by the gclass, never here).
+ ***************************************************************/
+
+/***************************************************************
+ *  Clamp an index into [0, count-1] (0 when there are no steps).
+ ***************************************************************/
+function wizard_clamp_index(idx, count)
+{
+    if(count <= 0) {
+        return 0;
+    }
+    if(idx < 0) {
+        return 0;
+    }
+    if(idx > count - 1) {
+        return count - 1;
+    }
+    return idx;
+}
+
+/***************************************************************
+ *  Next / previous index (clamped, never wrap).
+ ***************************************************************/
+function wizard_next_index(idx, count)
+{
+    return wizard_clamp_index(idx + 1, count);
+}
+
+function wizard_prev_index(idx, count)
+{
+    return wizard_clamp_index(idx - 1, count);
+}
+
+/***************************************************************
+ *  Chrome model for the current step.
+ *
+ *      opts = { allow_back, confirm_label, next_label }
+ *
+ *  Returns { idx, count, id, title, is_first, is_last,
+ *            show_back, primary_label }.
+ ***************************************************************/
+function wizard_step_model(steps, idx, opts)
+{
+    opts = opts || {};
+    let count = steps.length;
+    let i = wizard_clamp_index(idx, count);
+    let s = steps[i] || {};
+
+    let is_first = i <= 0;
+    let is_last  = i >= count - 1;
+
+    let primary_label;
+    if(is_last) {
+        primary_label = opts.confirm_label || "confirm";
+    } else {
+        primary_label = opts.next_label || "next";
+    }
+
+    return {
+        idx:           i,
+        count:         count,
+        id:            s.id || "",
+        title:         s.title || "",
+        is_first:      is_first,
+        is_last:       is_last,
+        show_back:     !!opts.allow_back && i > 0,
+        primary_label: primary_label,
+    };
+}
+
+/***************************************************************
+ *  Accumulate a step's validated kw.
+ *  Returns a NEW { merged, by_step } (never mutates).
+ ***************************************************************/
+function wizard_accumulate(acc, step_id, kw)
+{
+    if(!acc) {
+        acc = { merged: {}, by_step: {} };
+    }
+    kw = kw || {};
+    let merged  = Object.assign({}, acc.merged, kw);
+    let by_step = Object.assign({}, acc.by_step);
+    by_step[step_id] = kw;
+    return { merged: merged, by_step: by_step };
+}
+
+/***************************************************************
+ *  Whether the current step must be asked to validate before
+ *  advancing: only linear wizards, and only when the step has a
+ *  gobj that can answer EV_STEP_VALIDATE.
+ ***************************************************************/
+function wizard_should_validate(linear, has_gobj)
+{
+    return !!linear && !!has_gobj;
+}
+
+export {
+    wizard_clamp_index,
+    wizard_next_index,
+    wizard_prev_index,
+    wizard_step_model,
+    wizard_accumulate,
+    wizard_should_validate,
+};