@yuneta/gobj-ui 7.10.5 → 7.11.0

package/README.md

@@ -970,6 +970,67 @@ the middle, and **a toolbar left with a single group is centred**. An unknown
 name is reported, not silently dropped: a typo would otherwise remove the save
 button with no trace of why.
 
+### Selecting rows in any table — `yui_table_select.js`
+
+Deleting twenty rows one confirmation at a time is not a workflow. Any view
+whose table can remove (or export, or act on) a row eventually needs to do it
+to several at once, so the checkbox column, the settings behind it and the bar
+that appears while something is ticked live here once:
+
+```js
+import {
+    yui_selection_column,
+    yui_selection_settings,
+    yui_selection_bar,
+    yui_wire_selection,
+    yui_selected_rows,
+    yui_clear_selection,
+} from "@yuneta/gobj-ui/src/yui_table_select.js";
+
+/*  1. the column, FIRST in the list  */
+let columns = [yui_selection_column(), ...my_columns];
+
+/*  2. the settings it needs  */
+let table = new Tabulator($div, {...yui_selection_settings(), columns: columns, ...});
+
+/*  3. the bar. Every button's job is to SEND AN EVENT  */
+priv.bar = yui_selection_bar(t, {
+    name:    "CONNECTIONS",
+    actions: [{
+        label:    "remove selected",        /*  an i18n KEY  */
+        icon:     "yi-trash",
+        class:    "is-danger",
+        on_click: () => gobj_send_event(gobj, "EV_REMOVE_SELECTED", {}, gobj)
+    }],
+    on_clear: () => gobj_send_event(gobj, "EV_CLEAR_SELECTION", {}, gobj)
+});
+$container.appendChild(priv.bar.$el);
+
+/*  4. the table tells the bar how many are ticked  */
+yui_wire_selection(table, (n) => gobj_send_event(gobj, "EV_SELECTION_CHANGED",
+    {count: n}, gobj));
+```
+
+Two decisions are baked in, both learned in the treedb topic table:
+
+- **Selection is driven only by the checkbox** (`selectableRows: "highlight"`),
+  never by clicking the row. A row is full of things to click — an editor, an
+  icon, a nested table — and click-to-select ticks a row every time you reach
+  for one of them.
+- **The header checkbox covers the ACTIVE rows**, the ones the filters leave on
+  screen (`titleFormatterParams: {rowRange: "active"}`). "Select all" over rows
+  nobody can see is how a filtered delete takes the whole topic with it.
+
+The bar takes its words from the HOST's `t` (this library translates through
+the app's i18next): the app must define **`"{{n}} selected"`** and
+**`"clear selection"`**, and each action's own key. The count is composed at
+render time, so `refresh_language()` cannot reach it — call `bar.refresh()`
+from the view's `EV_LANGUAGE_CHANGED` action.
+
+`yui_selected_rows(table)` and `yui_clear_selection(table)` answer safely on a
+table that is not built yet or is already gone. Clear the selection after
+acting on it: the rows it names are no longer there.
+
 ## Conventions
 
 ### i18n: a string must be able to CHANGE language, not just be translated once

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuneta/gobj-ui",
-  "version": "7.10.5",
+  "version": "7.11.0",
   "type": "module",
   "main": "dist/gobj-ui.cjs.js",
   "module": "dist/gobj-ui.es.js",

package/src/yui_table_select.js

@@ -0,0 +1,231 @@
+/***********************************************************************
+ *          yui_table_select.js
+ *
+ *          SELECT ROWS IN A TABLE, and act on the lot.
+ *
+ *          Deleting twenty rows one confirmation at a time is not a
+ *          workflow, it is a punishment, and every table that lets you
+ *          remove a row will eventually be asked to remove twenty. This
+ *          is that facility, once: the checkbox column, the settings
+ *          that make selection behave, and the bar that appears while
+ *          something is selected and carries what can be done to it.
+ *
+ *          Two decisions are baked in, both learned in the treedb
+ *          topic table:
+ *
+ *          - Selection is driven ONLY by the checkbox, never by
+ *            clicking the row (`selectableRows: "highlight"`). A table
+ *            row is full of things to click -- an editor, an icon, a
+ *            nested table -- and click-to-select ticks a row every time
+ *            you reach for one of them.
+ *
+ *          - The header checkbox covers the ACTIVE rows, the ones the
+ *            filters leave on screen. "Select all" over rows nobody can
+ *            see is how a filtered delete takes the whole topic with
+ *            it.
+ *
+ *          The bar takes its words from the HOST's `t`: this library
+ *          translates through the app's i18next, and the app owns the
+ *          keys. It needs "{{n}} selected" and "clear selection"; each
+ *          action brings its own key.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import {createElement2, log_error} from "@yuneta/gobj-js";
+
+/***************************************************************
+ *      The checkbox column. Put it FIRST in the column list.
+ *
+ *      opts:
+ *          field   the (virtual) field name, default "_select"
+ *          width   default 44
+ ***************************************************************/
+function yui_selection_column(opts)
+{
+    let o = opts || {};
+    return {
+        title:                "",
+        field:                o.field || "_select",
+        width:                o.width || 44,
+        minWidth:             o.width || 44,
+        hozAlign:             "center",
+        headerHozAlign:       "center",
+        headerSort:           false,
+        resizable:            false,
+        formatter:            "rowSelection",
+        titleFormatter:       "rowSelection",
+        /*  The header ticks what is ON SCREEN, not what the filters hide. */
+        titleFormatterParams: {rowRange: "active"},
+        cssClass:             "TABLE_SELECT_CELL"
+    };
+}
+
+/***************************************************************
+ *      What the Tabulator settings need for the column above.
+ *      Spread it into the settings object.
+ ***************************************************************/
+function yui_selection_settings()
+{
+    return {selectableRows: "highlight"};
+}
+
+/***************************************************************
+ *      The rows selected right now (never null).
+ ***************************************************************/
+function yui_selected_rows(tabulator)
+{
+    if(!tabulator || typeof tabulator.getSelectedData !== "function") {
+        return [];
+    }
+    try {
+        return tabulator.getSelectedData() || [];
+    } catch(e) {
+        return [];      /*  asked before the table was built  */
+    }
+}
+
+/***************************************************************
+ *      Drop the selection (after acting on it, or after a
+ *      reload that leaves the ticked rows behind).
+ ***************************************************************/
+function yui_clear_selection(tabulator)
+{
+    if(!tabulator || typeof tabulator.deselectRow !== "function") {
+        return;
+    }
+    try {
+        tabulator.deselectRow();
+    } catch(e) {
+        /*  the table is gone: there is no selection to drop  */
+    }
+}
+
+/***************************************************************
+ *      Tell me when the selection changes.
+ *
+ *      `on_change(count)` is a DOM/widget notification and nothing
+ *      else: in a gclass its whole job is to SEND AN EVENT.
+ ***************************************************************/
+function yui_wire_selection(tabulator, on_change)
+{
+    if(!tabulator || typeof tabulator.on !== "function") {
+        log_error("yui_wire_selection(): no tabulator");
+        return;
+    }
+    if(typeof on_change !== "function") {
+        log_error("yui_wire_selection(): on_change is not a function");
+        return;
+    }
+    tabulator.on("rowSelectionChanged", function(data) {
+        on_change((data && data.length) || 0);
+    });
+}
+
+/***************************************************************
+ *      The bar that appears while rows are selected.
+ *
+ *      t           the HOST's translator
+ *      opts:
+ *          actions   [{label, icon, class, on_click}] -- `label` is an
+ *                    i18n KEY, `class` extra Bulma classes for the
+ *                    button (e.g. "is-danger"), `on_click` the DOM
+ *                    handler, whose job is to send an event
+ *          on_clear  called by the "clear selection" button
+ *          name      logical-class prefix, default "TABLE"
+ *
+ *      -> {$el, set_count(n), refresh()}
+ *
+ *      `refresh()` redraws it in the current language: the count is
+ *      composed at render time, so it cannot re-translate itself
+ *      through `refresh_language()`. Call it on EV_LANGUAGE_CHANGED.
+ ***************************************************************/
+function yui_selection_bar(t, opts)
+{
+    let o = opts || {};
+    let actions = Array.isArray(o.actions) ? o.actions : [];
+    let name = o.name || "TABLE";
+    let count = 0;
+
+    let $count = createElement2(
+        ["span", {class: `${name}_SELECTION_COUNT has-text-weight-semibold`}, ""]);
+
+    let $buttons = [];
+    for(let action of actions) {
+        let $b = createElement2(
+            ["button", {class: `${name}_SELECTION_ACTION button ${action.class || ""}`,
+                        type: "button"}, [
+                ["span", {class: "icon"}, [["i", {class: action.icon || "yi-check"}]]],
+                ["span", {}, ""]
+            ], {
+                click: action.on_click
+            }]
+        );
+        $b._yui_label = action.label || "";
+        $buttons.push($b);
+    }
+
+    let $clear = createElement2(
+        ["button", {class: `${name}_SELECTION_CLEAR button is-ghost`, type: "button"}, [
+            ["span", {class: "icon"}, [["i", {class: "yi-xmark"}]]],
+            ["span", {}, ""]
+        ], {
+            click: function(e) {
+                if(typeof o.on_clear === "function") {
+                    o.on_clear(e);
+                }
+            }
+        }]
+    );
+    $clear._yui_label = "clear selection";
+
+    let $el = createElement2(
+        ["div", {class: `${name}_SELECTION_BAR is-flex is-align-items-center `
+                      + "is-flex-wrap-wrap mb-2 is-hidden",
+                 style: "gap:0.5rem;"},
+            [$count].concat($buttons, [$clear])]
+    );
+
+    function label_of($b)
+    {
+        /*  The second span: the icon carries the first one. */
+        return $b.querySelector("span.icon ~ span");
+    }
+
+    function refresh()
+    {
+        $count.textContent = t("{{n}} selected", {n: count});
+        for(let $b of $buttons.concat([$clear])) {
+            let $label = label_of($b);
+            let key = $b._yui_label;
+            if($label && key) {
+                $label.textContent = t(key);
+            }
+            $b.title = key ? t(key) : "";
+            $b.setAttribute("aria-label", $b.title);
+        }
+        /*  Bulma's `is-hidden` carries `!important`: the class is what
+         *  toggles, an inline display would lose to it. */
+        $el.classList.toggle("is-hidden", count <= 0);
+    }
+
+    function set_count(n)
+    {
+        count = n > 0 ? n : 0;
+        refresh();
+    }
+
+    refresh();
+
+    return {$el: $el, set_count: set_count, refresh: refresh};
+}
+
+
+export {
+    yui_selection_column,
+    yui_selection_settings,
+    yui_selected_rows,
+    yui_clear_selection,
+    yui_wire_selection,
+    yui_selection_bar,
+};

package/src/yui_table_select.test.js

@@ -0,0 +1,54 @@
+/***********************************************************************
+ *          yui_table_select.test.js
+ *
+ *      The part of the facility that is not DOM: what the checkbox
+ *      column is, and reading a selection out of a table that may not
+ *      be there any more. The bar itself is DOM, like every other view
+ *      in this library, and this suite has no DOM.
+ ***********************************************************************/
+import { test, expect, describe } from "vitest";
+import {
+    yui_selection_column,
+    yui_selection_settings,
+    yui_selected_rows,
+    yui_clear_selection,
+} from "./yui_table_select.js";
+
+describe("the column", () => {
+    test("is a rowSelection checkbox that does not sort", () => {
+        let col = yui_selection_column();
+        expect(col.formatter).toBe("rowSelection");
+        expect(col.titleFormatter).toBe("rowSelection");
+        expect(col.headerSort).toBe(false);
+    });
+
+    test("the header ticks the rows the filters leave on screen", () => {
+        expect(yui_selection_column().titleFormatterParams).toEqual({rowRange: "active"});
+    });
+
+    test("the row itself is not clickable into selection", () => {
+        expect(yui_selection_settings()).toEqual({selectableRows: "highlight"});
+    });
+});
+
+describe("reading and dropping the selection", () => {
+    test("a table that is not built yet has nothing selected", () => {
+        expect(yui_selected_rows(null)).toEqual([]);
+        expect(yui_selected_rows({})).toEqual([]);
+    });
+
+    test("a table that throws has nothing selected either", () => {
+        expect(yui_selected_rows({getSelectedData: () => { throw new Error("gone"); }}))
+            .toEqual([]);
+    });
+
+    test("the rows come back as the table gives them", () => {
+        expect(yui_selected_rows({getSelectedData: () => [{id: "a"}]})).toEqual([{id: "a"}]);
+    });
+
+    test("clearing a table that is gone is not a crash", () => {
+        expect(() => yui_clear_selection(null)).not.toThrow();
+        expect(() => yui_clear_selection({deselectRow: () => { throw new Error("gone"); }}))
+            .not.toThrow();
+    });
+});