@visns-studio/visns-components 6.3.7 → 6.3.9

package/package.json

@@ -91,7 +91,7 @@
         "react-dom": "^17.0.0 || ^18.0.0"
     },
     "name": "@visns-studio/visns-components",
-    "version": "6.3.7",
+    "version": "6.3.9",
     "description": "Various packages to assist in the development of our Custom Applications.",
     "main": "src/index.js",
     "files": [

package/src/components/DataGrid.jsx

@@ -75,6 +75,13 @@ import {
     AlertCircle,
     CheckCheck,
     Plus,
+    // treeGroupBy parent rows: ChevronDown is the collapse control in BOTH
+    // states — it is rotated rather than swapped for ChevronRight, so the
+    // glyph turns between them instead of popping, and the direction it
+    // points is the state. ListPlus is the "add another to this group"
+    // affordance, which a bare Plus does not say on its own.
+    ChevronDown,
+    ListPlus,
 } from 'lucide-react';
 import styles from './styles/DataGrid.module.scss';
 
@@ -659,11 +666,11 @@ const DataGrid = forwardRef(
                     }
 
                     // Opt-in grouped display (ajaxSetting.treeGroupBy {key,
-                    // column, parentFields, countLabel, collapsible,
-                    // defaultCollapsed, icons}): consecutive rows sharing a
-                    // non-empty `key` value get a synthetic summary parent
-                    // row inserted above them. `parentFields` are lifted from
-                    // the first row onto the parent and blanked on the
+                    // column, parentFields, parentFieldAliases, countLabel,
+                    // collapsible, defaultCollapsed, icons}): consecutive rows
+                    // sharing a non-empty `key` value get a synthetic summary
+                    // parent row inserted above them. `parentFields` are lifted
+                    // from the first row onto the parent and blanked on the
                     // children, so shared details display once; children get
                     // an "↳" prefix in the display column. Single rows stay
                     // plain — unlike the grid's own groupBy, which forces a
@@ -678,6 +685,7 @@ const DataGrid = forwardRef(
                             key: treeKey,
                             column: treeDisplayColumn,
                             parentFields = [],
+                            parentFieldAliases = {},
                             countLabel,
                             collapsible,
                             defaultCollapsed,
@@ -722,6 +730,35 @@ const DataGrid = forwardRef(
                                     });
                                 });
 
+                                // `parentFieldAliases` ({columnField:
+                                // sourceField}): the parent shows a DIFFERENT
+                                // field in a column than its children do, so
+                                // one column can carry the per-member value on
+                                // members and the group's summary on the
+                                // parent instead of spending a second column
+                                // on the summary alone.
+                                //
+                                // Unlike `parentFields` this deliberately does
+                                // NOT blank the column on the children — the
+                                // members' own values are the reason the
+                                // column exists. (Listing the same field in
+                                // both would blank it on the children and
+                                // defeat that, so pick one.)
+                                //
+                                // Distinct from `countLabel` too, which
+                                // templates a summary from the child COUNT and
+                                // so can only produce one fixed wording. An
+                                // alias reads a field the backend computed,
+                                // which is what it takes for the summary to
+                                // vary with the data ("2 Headers" for one kind
+                                // of group, "2 Stations" for another).
+                                Object.entries(parentFieldAliases).forEach(
+                                    ([columnField, sourceField]) => {
+                                        parent[columnField] =
+                                            children[0]?.[sourceField];
+                                    }
+                                );
+
                                 // Mark children for styling (getRowStyle) and
                                 // prefix their display value so nesting reads
                                 children.forEach((child) => {
@@ -1796,6 +1833,10 @@ const DataGrid = forwardRef(
                     return CheckCheck;
                 case 'plus':
                     return Plus;
+                // A separate id rather than a re-point of `plus`: every other
+                // project's `plus` icon must keep the glyph it has always had.
+                case 'listPlus':
+                    return ListPlus;
                 case 'edit':
                     return Edit;
                 case 'envelope':
@@ -4110,9 +4151,125 @@ const DataGrid = forwardRef(
                         };
                     };
 
+                    /**
+                     * The group's collapse control.
+                     *
+                     * One glyph in both states: ChevronDown, turned a quarter
+                     * to point right when the group is shut. That is the
+                     * idiom every tree in every file manager uses, and it
+                     * animates — a "+"/"−" pair swaps two unrelated marks and
+                     * says nothing about direction. `relocated` picks the
+                     * class set, since the controls-column variant is sized
+                     * for a fingertip and must not inherit the inline one's
+                     * legacy dimensions.
+                     *
+                     * aria-expanded carries the state for assistive tech, so
+                     * the meaning does not depend on seeing the rotation.
+                     */
+                    const renderTreeCollapseControl = (
+                        groupValue,
+                        collapsed,
+                        relocated
+                    ) => (
+                        <button
+                            type="button"
+                            className={
+                                relocated
+                                    ? `tree-control-btn ${styles.treeControlBtn} ${styles.treeControlChevron}`
+                                    : `group-expand-btn ${styles.groupExpandBtn}`
+                            }
+                            aria-expanded={!collapsed}
+                            aria-label={
+                                collapsed ? 'Expand group' : 'Collapse group'
+                            }
+                            onClick={(e) => {
+                                e.stopPropagation();
+                                toggleTreeGroup(groupValue);
+                            }}
+                            data-tooltip-id="system-tooltip"
+                            data-tooltip-content={
+                                collapsed ? 'Expand group' : 'Collapse group'
+                            }
+                        >
+                            {relocated ? (
+                                <ChevronDown
+                                    className={
+                                        collapsed
+                                            ? styles.treeChevronCollapsed
+                                            : styles.treeChevronExpanded
+                                    }
+                                    strokeWidth={2.25}
+                                    size={18}
+                                    aria-hidden="true"
+                                />
+                            ) : collapsed ? (
+                                '+'
+                            ) : (
+                                '−'
+                            )}
+                        </button>
+                    );
+
+                    /** The group's treeGroupBy.icons, in either placement. */
+                    const renderTreeGroupIcons = (groupValue, relocated) =>
+                        (ajaxSetting?.treeGroupBy?.icons || []).map(
+                            (iconConfig, index) => {
+                                if (
+                                    !shouldShowGroupAction(
+                                        iconConfig,
+                                        groupValue
+                                    )
+                                ) {
+                                    return null;
+                                }
+
+                                const IconComponent = getGroupIconComponent(
+                                    iconConfig.id
+                                );
+                                const colour = iconConfig.colour || 'success';
+
+                                return (
+                                    <button
+                                        type="button"
+                                        key={`tree-action-${index}`}
+                                        className={
+                                            relocated
+                                                ? `tree-control-btn tree-control-${iconConfig.id}-btn ${styles.treeControlBtn} ${styles[colour] || ''}`
+                                                : `group-action-btn ${styles.groupActionBtn} ${styles[colour] || ''}`
+                                        }
+                                        aria-label={iconConfig.label}
+                                        onClick={(e) => {
+                                            e.stopPropagation();
+                                            handleGroupAction(
+                                                groupValue,
+                                                iconConfig
+                                            );
+                                        }}
+                                        data-tooltip-id="system-tooltip"
+                                        data-tooltip-content={iconConfig.label}
+                                    >
+                                        <IconComponent
+                                            strokeWidth={2}
+                                            size={relocated ? 18 : 14}
+                                            aria-hidden="true"
+                                        />
+                                    </button>
+                                );
+                            }
+                        );
+
                     // The tree parent's display column doubles as the group's
                     // header line: expand/collapse plus any treeGroupBy.icons
                     // whose show/showAll conditions the group's rows satisfy.
+                    //
+                    // `controlsColumn` (opt-in) moves those controls into
+                    // ANOTHER column's cell on parent rows, leaving the label
+                    // cell to the label alone. Parent rows blank most
+                    // interactive columns (TREE_PARENT_BLOCKED_TYPES), so a
+                    // grid usually has an empty cell going spare while the
+                    // label is squeezed between two buttons — this spends that
+                    // space instead. Unset (the default) keeps the controls
+                    // inline exactly as they have always rendered.
                     const decorateTreeParentActions = (
                         gridColumn,
                         columnDef
@@ -4125,12 +4282,29 @@ const DataGrid = forwardRef(
                         if (
                             !tree?.key ||
                             !tree.column ||
-                            tree.column !== columnId ||
                             !(tree.collapsible || tree.icons?.length)
                         ) {
                             return gridColumn;
                         }
 
+                        // Pointing controlsColumn at the label column is the
+                        // inline layout, so treat it as unset rather than
+                        // rendering the controls into the cell twice.
+                        const controlsColumn =
+                            tree.controlsColumn &&
+                            tree.controlsColumn !== tree.column
+                                ? tree.controlsColumn
+                                : null;
+
+                        const isLabelColumn = tree.column === columnId;
+                        const isControlsColumn =
+                            controlsColumn !== null &&
+                            controlsColumn === columnId;
+
+                        if (!isLabelColumn && !isControlsColumn) {
+                            return gridColumn;
+                        }
+
                         const originalRender = gridColumn.render;
 
                         return {
@@ -4147,28 +4321,44 @@ const DataGrid = forwardRef(
                                 const groupValue = data[tree.key];
                                 const collapsed = data.__treeCollapsed === true;
 
+                                // Relocated placement: this cell carries the
+                                // controls and nothing else.
+                                if (isControlsColumn) {
+                                    return (
+                                        <div
+                                            className={
+                                                styles.treeParentControls
+                                            }
+                                            onClick={(e) =>
+                                                e.stopPropagation()
+                                            }
+                                        >
+                                            {tree.collapsible &&
+                                                renderTreeCollapseControl(
+                                                    groupValue,
+                                                    collapsed,
+                                                    true
+                                                )}
+                                            {renderTreeGroupIcons(
+                                                groupValue,
+                                                true
+                                            )}
+                                        </div>
+                                    );
+                                }
+
                                 return (
                                     <div
                                         className={styles.treeParentHeader}
                                         onClick={(e) => e.stopPropagation()}
                                     >
-                                        {tree.collapsible && (
-                                            <button
-                                                className={`group-expand-btn ${styles.groupExpandBtn}`}
-                                                onClick={(e) => {
-                                                    e.stopPropagation();
-                                                    toggleTreeGroup(groupValue);
-                                                }}
-                                                data-tooltip-id="system-tooltip"
-                                                data-tooltip-content={
-                                                    collapsed
-                                                        ? 'Expand group'
-                                                        : 'Collapse group'
-                                                }
-                                            >
-                                                {collapsed ? '+' : '−'}
-                                            </button>
-                                        )}
+                                        {!controlsColumn &&
+                                            tree.collapsible &&
+                                            renderTreeCollapseControl(
+                                                groupValue,
+                                                collapsed,
+                                                false
+                                            )}
                                         <strong
                                             className={styles.treeParentLabel}
                                         >
@@ -4177,53 +4367,11 @@ const DataGrid = forwardRef(
                                                 ? ` (${data.__treeChildCount})`
                                                 : ''}
                                         </strong>
-                                        {(tree.icons || []).map(
-                                            (iconConfig, index) => {
-                                                if (
-                                                    !shouldShowGroupAction(
-                                                        iconConfig,
-                                                        groupValue
-                                                    )
-                                                ) {
-                                                    return null;
-                                                }
-
-                                                const IconComponent =
-                                                    getGroupIconComponent(
-                                                        iconConfig.id
-                                                    );
-
-                                                return (
-                                                    <button
-                                                        key={`tree-action-${index}`}
-                                                        className={`group-action-btn ${
-                                                            styles.groupActionBtn
-                                                        } ${
-                                                            styles[
-                                                                iconConfig.colour ||
-                                                                    'success'
-                                                            ] || ''
-                                                        }`}
-                                                        onClick={(e) => {
-                                                            e.stopPropagation();
-                                                            handleGroupAction(
-                                                                groupValue,
-                                                                iconConfig
-                                                            );
-                                                        }}
-                                                        data-tooltip-id="system-tooltip"
-                                                        data-tooltip-content={
-                                                            iconConfig.label
-                                                        }
-                                                    >
-                                                        <IconComponent
-                                                            strokeWidth={2}
-                                                            size={14}
-                                                        />
-                                                    </button>
-                                                );
-                                            }
-                                        )}
+                                        {!controlsColumn &&
+                                            renderTreeGroupIcons(
+                                                groupValue,
+                                                false
+                                            )}
                                     </div>
                                 );
                             },

package/src/components/styles/DataGrid.module.scss

@@ -1402,3 +1402,180 @@
         opacity: var(--grid-row-complete-opacity, 0.7);
     }
 }
+
+/* =========================================================================
+   treeGroupBy relocated group controls (`treeGroupBy.controlsColumn`)
+
+   When the controls move out of the label cell they stop being decoration
+   squeezed beside a tag and become the row's primary affordance, so they are
+   sized as targets rather than as glyphs. They also get class names of their
+   own rather than reusing `.groupExpandBtn` / `.groupActionBtn`: consuming
+   projects have `!important` rules pinned to those (hartway clamps them to
+   38px in tablet mode), and inheriting a size tuned for the cramped inline
+   layout is exactly what this placement exists to escape.
+
+   Meaning never rests on colour: each control carries a glyph, the collapse
+   state is carried by the chevron's rotation AND by aria-expanded, and the
+   colour classes below are the same decorative palette the inline buttons
+   use. A greyscale screen loses nothing.
+
+   Density hooks, per the `--nav-*` / `--grid-legend-*` convention above:
+
+     --grid-tree-control-size         control box, pointer input.  default: 32px
+     --grid-tree-control-size-tablet  control box under body.tablet-mode.
+                                      default: 44px — the tap-target floor for
+                                      a gloved hand on the plant floor, and the
+                                      reason this placement is worth having.
+     --grid-tree-control-gap          space between controls.      default: 6px
+   ========================================================================= */
+
+.treeParentControls {
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    gap: var(--grid-tree-control-gap, 6px);
+    width: 100%;
+    height: 100%;
+}
+
+.treeControlBtn {
+    flex-shrink: 0;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    width: var(--grid-tree-control-size, 32px);
+    height: var(--grid-tree-control-size, 32px);
+    min-width: var(--grid-tree-control-size, 32px);
+    min-height: var(--grid-tree-control-size, 32px);
+    padding: 0;
+    border: none;
+    border-radius: var(--radius-sm, 6px);
+    background: var(--primary-color, #3b82f6);
+    color: white;
+    cursor: pointer;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12);
+    transition: background 0.2s ease, box-shadow 0.2s ease,
+        transform 0.1s ease;
+
+    &:hover {
+        box-shadow: 0 3px 6px rgba(0, 0, 0, 0.18);
+    }
+
+    &:active {
+        transform: scale(0.94);
+    }
+
+    // A keyboard user has to be able to see which control is theirs; the grid
+    // suppresses its own outline inside cells, so state it here.
+    &:focus-visible {
+        outline: 2px solid var(--primary-color, #3b82f6);
+        outline-offset: 2px;
+    }
+
+    // Colour variants, matching `.groupActionBtn`'s set so an icon config
+    // reads the same in either placement.
+    &.success {
+        background: var(--success-color, #10b981);
+        &:hover {
+            background: var(--success-hover-color, #059669);
+        }
+    }
+
+    &.warning {
+        background: var(--warning-color, #f59e0b);
+        &:hover {
+            background: var(--warning-hover-color, #d97706);
+        }
+    }
+
+    &.info {
+        background: var(--info-color, #3b82f6);
+        &:hover {
+            background: var(--info-hover-color, #2563eb);
+        }
+    }
+
+    &.purple {
+        background: var(--purple-color, #8b5cf6);
+        &:hover {
+            background: var(--purple-hover-color, #7c3aed);
+        }
+    }
+
+    &.pink {
+        background: var(--pink-color, #ec4899);
+        &:hover {
+            background: var(--pink-hover-color, #db2777);
+        }
+    }
+}
+
+/* The collapse control is deliberately quieter than the action buttons: it
+   changes what you can see, not what the plant has done, so it reads as
+   chrome rather than as a fourth coloured button competing with them. */
+.treeControlChevron {
+    background: rgba(var(--paragraph-color-rgb, 34, 30, 51), 0.08);
+    color: var(--paragraph-color, #374151);
+    box-shadow: none;
+
+    &:hover {
+        background: rgba(var(--paragraph-color-rgb, 34, 30, 51), 0.16);
+        box-shadow: none;
+    }
+}
+
+.treeChevronExpanded,
+.treeChevronCollapsed {
+    transition: transform 0.18s ease;
+}
+
+.treeChevronExpanded {
+    transform: rotate(0deg);
+}
+
+/* Shut: the chevron points at the row it would open, the same way every
+   file tree in the world points at a closed folder. */
+.treeChevronCollapsed {
+    transform: rotate(-90deg);
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .treeChevronExpanded,
+    .treeChevronCollapsed {
+        transition: none;
+    }
+}
+
+/* Tablet mode is a bench at arm's length worked with gloves on, so the
+   controls step up to the 44px tap-target floor. Scoped to body.tablet-mode,
+   the same signal the package already styles against in global-datagrid.css.
+   The grid's tablet rows are 52px, so 44px still clears the row edges. */
+:global(body.tablet-mode) {
+    .treeControlBtn {
+        width: var(--grid-tree-control-size-tablet, 44px);
+        height: var(--grid-tree-control-size-tablet, 44px);
+        min-width: var(--grid-tree-control-size-tablet, 44px);
+        min-height: var(--grid-tree-control-size-tablet, 44px);
+        border-radius: var(--radius-md, 8px);
+    }
+
+    .treeParentControls {
+        gap: var(--grid-tree-control-gap, 8px);
+
+        /* A tablet row is a fixed 52px and the grid pads its cells 6px top
+           and bottom, leaving a 40px content box — 4px short of the floor
+           this placement exists to clear. This strip IS the whole cell's
+           content and its buttons carry their own spacing, so it reclaims
+           that padding rather than letting the control shrink to fit.
+           Negative margin rather than overflow: the 44px control then sits
+           inside the row's own 52px border box, so a cell that hides its
+           overflow has nothing to clip.
+
+             --grid-tree-control-cell-inset  cell padding to reclaim.
+                                             default: 6px */
+        margin-block: calc(
+            -1 * var(--grid-tree-control-cell-inset, 6px)
+        );
+    }
+}