@yuneta/gobj-ui 2.2.4 → 2.3.0

package/src/nav_cards_helpers.js

@@ -0,0 +1,71 @@
+/***********************************************************************
+ *          nav_cards_helpers.js
+ *
+ *      Pure descriptor builders for C_YUI_NAV's "cards" layout — a
+ *      grid of tappable cards, one per item, used as the section-index
+ *      landing of a submenu (list → detail pattern).  Split out of
+ *      c_yui_nav.js so it can be unit-tested without a DOM: the
+ *      functions return createElement2 node descriptors, never
+ *      HTMLElements.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/************************************************************
+ *  Descriptor of one card: an <a> carrying the same data-*
+ *  contract as every other nav item (data-route/data-item-id/
+ *  data-disabled), so C_YUI_NAV's delegated click handler and
+ *  active-route highlight work unchanged.
+ ************************************************************/
+export function card_descriptor(it, show_label)
+{
+    let children = [];
+    let label = it.name || "";
+
+    if(it.icon) {
+        children.push(["span", {class: "icon is-medium"},
+            ["i", {class: it.icon, "aria-hidden": "true"}]]);
+    }
+    if(show_label && label) {
+        children.push(["span", {class: "yui-nav-label", i18n: label}, label]);
+    }
+
+    let a_attrs = {
+        class: "yui-nav-item yui-nav-card",
+        href: it.route ? "#" + it.route : "#",
+        "data-item-id": it.id,
+        "data-route": it.route || "",
+        "data-disabled": it.disabled ? "1" : "0",
+        "aria-label": label || it.id
+    };
+    if(label) {
+        a_attrs["data-i18n-aria-label"] = label;
+    }
+    let tip = it.tooltip || it.aria_label;
+    if(tip) {
+        a_attrs.title = tip;
+        a_attrs["data-i18n-title"] = tip;
+    }
+    if(it.disabled) {
+        a_attrs["aria-disabled"] = "true";
+        a_attrs["tabindex"] = "-1";
+    }
+    return ["a", a_attrs, children];
+}
+
+/************************************************************
+ *  Descriptor of the whole grid.  Decorative items (`header`/
+ *  `divider`) are dropped, same policy as the tabs layout.
+ ************************************************************/
+export function cards_grid_descriptor(items, show_label)
+{
+    let cards = [];
+    for(let it of (items || [])) {
+        if(!it || it.type === "header" || it.type === "divider") {
+            continue;
+        }
+        cards.push(card_descriptor(it, show_label));
+    }
+    return ["div", {}, cards];
+}

package/src/nav_cards_helpers.test.js

@@ -0,0 +1,122 @@
+/***********************************************************************
+ *          nav_cards_helpers.test.js
+ *
+ *      Unit tests for the pure "cards" layout descriptor builders.
+ *      Descriptors are plain createElement2 arrays, so no DOM needed.
+ ***********************************************************************/
+import { test, expect } from "vitest";
+import {
+    card_descriptor,
+    cards_grid_descriptor,
+} from "./nav_cards_helpers.js";
+
+
+/***************************************************************
+ *  card_descriptor
+ ***************************************************************/
+test("card carries the nav item data-* contract", () => {
+    let [tag, attrs, children] = card_descriptor(
+        {id: "budgets", name: "budgets", icon: "wzi-coins", route: "/reports/budgets"},
+        true
+    );
+    expect(tag).toBe("a");
+    expect(attrs["data-item-id"]).toBe("budgets");
+    expect(attrs["data-route"]).toBe("/reports/budgets");
+    expect(attrs["data-disabled"]).toBe("0");
+    expect(attrs.href).toBe("#/reports/budgets");
+    expect(attrs["aria-label"]).toBe("budgets");
+    expect(attrs["data-i18n-aria-label"]).toBe("budgets");
+    expect(attrs.class).toContain("yui-nav-card");
+
+    let [icon_tag, icon_attrs] = children[0];
+    expect(icon_tag).toBe("span");
+    expect(icon_attrs.class).toContain("icon");
+
+    let [label_tag, label_attrs, label_text] = children[1];
+    expect(label_tag).toBe("span");
+    expect(label_attrs.i18n).toBe("budgets");
+    expect(label_text).toBe("budgets");
+});
+
+test("card without icon renders label only", () => {
+    let [, , children] = card_descriptor(
+        {id: "x", name: "x label", route: "/x"},
+        true
+    );
+    expect(children.length).toBe(1);
+    expect(children[0][0]).toBe("span");
+    expect(children[0][2]).toBe("x label");
+});
+
+test("show_label=false drops the label span", () => {
+    let [, attrs, children] = card_descriptor(
+        {id: "x", name: "x label", icon: "yi-gear", route: "/x"},
+        false
+    );
+    expect(children.length).toBe(1);
+    expect(children[0][1].class).toContain("icon");
+    /*  aria still carries the name for icon-only cards. */
+    expect(attrs["aria-label"]).toBe("x label");
+});
+
+test("disabled card is marked for the click handler and a11y", () => {
+    let [, attrs] = card_descriptor(
+        {id: "x", name: "x", route: "/x", disabled: true},
+        true
+    );
+    expect(attrs["data-disabled"]).toBe("1");
+    expect(attrs["aria-disabled"]).toBe("true");
+    expect(attrs["tabindex"]).toBe("-1");
+});
+
+test("tooltip mirrors into title + data-i18n-title", () => {
+    let [, attrs] = card_descriptor(
+        {id: "x", name: "x", route: "/x", tooltip: "the tip"},
+        true
+    );
+    expect(attrs.title).toBe("the tip");
+    expect(attrs["data-i18n-title"]).toBe("the tip");
+});
+
+test("item without route degrades to inert href '#'", () => {
+    let [, attrs] = card_descriptor({id: "x", name: "x"}, true);
+    expect(attrs.href).toBe("#");
+    expect(attrs["data-route"]).toBe("");
+});
+
+
+/***************************************************************
+ *  cards_grid_descriptor
+ ***************************************************************/
+test("grid renders one card per navigable item", () => {
+    let [tag, , cards] = cards_grid_descriptor(
+        [
+            {id: "a", name: "a", route: "/s/a"},
+            {id: "b", name: "b", route: "/s/b"},
+        ],
+        true
+    );
+    expect(tag).toBe("div");
+    expect(cards.length).toBe(2);
+    expect(cards[0][1]["data-route"]).toBe("/s/a");
+    expect(cards[1][1]["data-route"]).toBe("/s/b");
+});
+
+test("grid drops decorative items (same policy as tabs)", () => {
+    let [, , cards] = cards_grid_descriptor(
+        [
+            {type: "header", name: "group"},
+            {id: "a", name: "a", route: "/s/a"},
+            {type: "divider"},
+            {id: "b", name: "b", route: "/s/b"},
+            null,
+        ],
+        true
+    );
+    expect(cards.length).toBe(2);
+});
+
+test("grid tolerates empty/missing items", () => {
+    expect(cards_grid_descriptor([], true)[2].length).toBe(0);
+    expect(cards_grid_descriptor(null, true)[2].length).toBe(0);
+});

package/src/shell_section_index.js

@@ -0,0 +1,106 @@
+/***********************************************************************
+ *          shell_section_index.js
+ *
+ *      Pure helper for C_YUI_SHELL: synthesize the stage target of a
+ *      section-index landing route.
+ *
+ *      A level-1 menu item that declares `submenu.index` opts out of
+ *      the redirect-to-default-child behaviour: its own route becomes
+ *      a real resting, deep-linkable route whose view is the submenu
+ *      itself rendered as a "cards" C_YUI_NAV (the shell's view
+ *      contract only requires a $container by the end of mt_create,
+ *      which C_YUI_NAV already satisfies).  Config:
+ *
+ *          "submenu": {
+ *              "render": { "top-sub": "tabs" },
+ *              "index":  true            — landing in stage "main"
+ *              "index":  {"stage": "x"}  — landing in stage "x"
+ *          }
+ *
+ *      Precedence: an explicit inline `target` on the item wins (this
+ *      helper returns null then).  When the target is synthesized,
+ *      `submenu.default` becomes inert for the section: navigate_to()
+ *      only redirects to the default child while the entry has NO
+ *      target.
+ *
+ *      Tabs and cards never coexist (DRY of navigation): while the
+ *      index is on stage the shell collapses the secondary zone, and
+ *      for index sections the tab strip defaults to desktop/tablet
+ *      only — on mobile a "backbar" nav (← <section>) takes its place
+ *      inside a child view.  See secondary_nav_renders().
+ *
+ *      Split out of c_yui_shell.js so it can be unit-tested without
+ *      a DOM.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/************************************************************
+ *  Return the synthesized target for `item`'s section route,
+ *  or null when the item doesn't opt in.
+ ************************************************************/
+export function section_index_target(menu_id, item)
+{
+    if(!item || !item.route || item.target) {
+        return null;
+    }
+    let sub = item.submenu;
+    if(!sub || !Array.isArray(sub.items) || !sub.index) {
+        return null;
+    }
+    let index_cfg = (typeof sub.index === "object") ? sub.index : {};
+    return {
+        stage: index_cfg.stage || "main",
+        gclass: "C_YUI_NAV",
+        kw: {
+            menu_id: `index.${menu_id}.${item.id}`,
+            nav_label: item.name || item.id || "",
+            menu_items: sub.items,
+            layout: "cards",
+            level: "secondary"
+        }
+    };
+}
+
+/************************************************************
+ *  Return the list of render configs for one (submenu, zone)
+ *  pair.  `layout` is the raw submenu.render[zone] value
+ *  (string or object).
+ *
+ *  Without submenu.index: the declared render, unchanged.
+ *  With submenu.index (list → detail):
+ *      - the declared nav defaults to show_on ">=tablet" (an
+ *        explicit show_on in the render object wins);
+ *      - a "backbar" nav (show_on "<tablet") is appended so a
+ *        child view offers "← <section>" on mobile instead of
+ *        the duplicated tab strip.  Disable with
+ *        index: {backbar: false}; tune its breakpoints with
+ *        index: {backbar: {show_on: "..."}}.
+ ************************************************************/
+export function secondary_nav_renders(item, layout)
+{
+    let cfg = (layout && typeof layout === "object")
+        ? Object.assign({}, layout)
+        : {layout: String(layout || "vertical")};
+
+    let sub = (item && item.submenu) || {};
+    if(!sub.index) {
+        return [cfg];
+    }
+    let index_cfg = (typeof sub.index === "object") ? sub.index : {};
+    if(!cfg.show_on) {
+        cfg.show_on = ">=tablet";
+    }
+    if(index_cfg.backbar === false) {
+        return [cfg];
+    }
+    let backbar_cfg = (typeof index_cfg.backbar === "object" && index_cfg.backbar)
+        ? index_cfg.backbar
+        : {};
+    return [cfg, {
+        layout: "backbar",
+        show_on: backbar_cfg.show_on || "<tablet",
+        back_route: (item && item.route) || ""
+    }];
+}

package/src/shell_section_index.test.js

@@ -0,0 +1,151 @@
+/***********************************************************************
+ *          shell_section_index.test.js
+ *
+ *      Unit tests for the section-index target synthesis.
+ ***********************************************************************/
+import { test, expect } from "vitest";
+import {
+    section_index_target,
+    secondary_nav_renders,
+} from "./shell_section_index.js";
+
+
+const SUB_ITEMS = [
+    {id: "insights", name: "insights", route: "/reports/insights"},
+    {id: "budgets",  name: "budgets",  route: "/reports/budgets"},
+];
+
+function reports_item(extra_sub, extra_item)
+{
+    return Object.assign({
+        id: "reports",
+        name: "reports",
+        route: "/reports",
+        submenu: Object.assign({
+            render: {"top-sub": "tabs"},
+            items: SUB_ITEMS,
+        }, extra_sub || {}),
+    }, extra_item || {});
+}
+
+
+/***************************************************************
+ *  Opt-in gate
+ ***************************************************************/
+test("no submenu.index → null (redirect-to-default preserved)", () => {
+    expect(section_index_target("primary", reports_item())).toBe(null);
+});
+
+test("index=false → null", () => {
+    expect(section_index_target("primary", reports_item({index: false}))).toBe(null);
+});
+
+test("item without route → null", () => {
+    let item = reports_item({index: true});
+    delete item.route;
+    expect(section_index_target("primary", item)).toBe(null);
+});
+
+test("explicit inline target wins over index", () => {
+    let item = reports_item(
+        {index: true},
+        {target: {stage: "main", gclass: "C_APP_VIEW"}}
+    );
+    expect(section_index_target("primary", item)).toBe(null);
+});
+
+test("submenu without items array → null", () => {
+    let item = reports_item({index: true});
+    item.submenu.items = null;
+    expect(section_index_target("primary", item)).toBe(null);
+});
+
+test("no submenu at all → null", () => {
+    expect(section_index_target("primary", {id: "x", route: "/x"})).toBe(null);
+});
+
+
+/***************************************************************
+ *  Synthesis
+ ***************************************************************/
+test("index=true synthesizes a cards C_YUI_NAV target in stage 'main'", () => {
+    let t = section_index_target("primary", reports_item({index: true}));
+    expect(t).not.toBe(null);
+    expect(t.stage).toBe("main");
+    expect(t.gclass).toBe("C_YUI_NAV");
+    expect(t.kw.layout).toBe("cards");
+    expect(t.kw.level).toBe("secondary");
+    expect(t.kw.menu_id).toBe("index.primary.reports");
+    expect(t.kw.nav_label).toBe("reports");
+    /*  Same array reference: a later yui_shell_set_submenu() refresh
+     *  of kw.menu_items must be observable by the next mount. */
+    expect(t.kw.menu_items).toBe(SUB_ITEMS);
+});
+
+test("index={stage} overrides the stage", () => {
+    let t = section_index_target("primary", reports_item({index: {stage: "aux"}}));
+    expect(t.stage).toBe("aux");
+});
+
+test("nav_label falls back to the item id", () => {
+    let item = reports_item({index: true});
+    delete item.name;
+    let t = section_index_target("primary", item);
+    expect(t.kw.nav_label).toBe("reports");
+});
+
+
+/***************************************************************
+ *  secondary_nav_renders
+ ***************************************************************/
+test("no index → the declared render, unchanged, alone", () => {
+    let renders = secondary_nav_renders(reports_item(), {layout: "tabs"});
+    expect(renders).toEqual([{layout: "tabs"}]);
+});
+
+test("index → tabs constrained to >=tablet + mobile backbar", () => {
+    let renders = secondary_nav_renders(
+        reports_item({index: true}), {layout: "tabs"}
+    );
+    expect(renders.length).toBe(2);
+    expect(renders[0]).toEqual({layout: "tabs", show_on: ">=tablet"});
+    expect(renders[1]).toEqual({
+        layout: "backbar",
+        show_on: "<tablet",
+        back_route: "/reports"
+    });
+});
+
+test("explicit show_on on the declared render wins", () => {
+    let renders = secondary_nav_renders(
+        reports_item({index: true}), {layout: "tabs", show_on: ">=desktop"}
+    );
+    expect(renders[0].show_on).toBe(">=desktop");
+});
+
+test("index {backbar:false} suppresses the backbar", () => {
+    let renders = secondary_nav_renders(
+        reports_item({index: {backbar: false}}), {layout: "tabs"}
+    );
+    expect(renders.length).toBe(1);
+    expect(renders[0].show_on).toBe(">=tablet");
+});
+
+test("index {backbar:{show_on}} tunes the backbar breakpoints", () => {
+    let renders = secondary_nav_renders(
+        reports_item({index: {backbar: {show_on: "<desktop"}}}),
+        {layout: "tabs"}
+    );
+    expect(renders[1].show_on).toBe("<desktop");
+});
+
+test("string layout shorthand is normalized", () => {
+    let renders = secondary_nav_renders(reports_item(), "tabs");
+    expect(renders).toEqual([{layout: "tabs"}]);
+});
+
+test("input render object is not mutated", () => {
+    let declared = {layout: "tabs"};
+    secondary_nav_renders(reports_item({index: true}), declared);
+    expect(declared).toEqual({layout: "tabs"});
+});