@visns-studio/visns-components 6.20.1 → 6.23.0

package/package.json

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

package/src/components/DataGrid.jsx

@@ -37,10 +37,10 @@ import 'reactjs-popup/dist/index.css';
 import parse from 'html-react-parser';
 import { saveAs } from 'file-saver';
 import NumberFilter from '@visns-studio/visns-datagrid-enterprise/NumberFilter';
-import SelectFilter from '@visns-studio/visns-datagrid-enterprise/SelectFilter';
 import DateFilter from '@visns-studio/visns-datagrid-enterprise/DateFilter';
 import ReactDataGrid from '@visns-studio/visns-datagrid-enterprise';
 import NativeDateFilterEditor from './columns/NativeDateFilterEditor';
+import SelectFilterEditor from './columns/SelectFilterEditor';
 import { toast } from 'react-toastify';
 import fetchUtil from '../utils/fetchUtil';
 import { confirmDialog } from './utils/ConfirmDialog';
@@ -4387,7 +4387,11 @@ const DataGrid = forwardRef(
                                     filterEditor = NumberFilter;
                                     break;
                                 case 'select':
-                                    filterEditor = SelectFilter;
+                                    // The grid's own SelectFilter, wrapped so
+                                    // that opening a dropdown which already
+                                    // holds a value clears it — see
+                                    // SelectFilterEditor for the semantics.
+                                    filterEditor = SelectFilterEditor;
 
                                     // Inline options: `filter.options` as
                                     // [{ id, label }].
@@ -4424,6 +4428,15 @@ const DataGrid = forwardRef(
                                                 column.filter.searchable === false,
                                             // Explicitly enable clear icon
                                             clearIcon: true,
+                                            // Opening a filled dropdown clears
+                                            // it (see SelectFilterEditor). A
+                                            // column that must always carry a
+                                            // value opts out with
+                                            // `filter: { clearOnOpen: false }`;
+                                            // a multi-select, excluded by
+                                            // default, opts in with `true`.
+                                            clearOnOpen:
+                                                column.filter.clearOnOpen,
                                         };
                                     } else {
                                         // Show loading state for URL-based filters without data

package/src/components/Navigation.jsx

@@ -1,6 +1,7 @@
 import React, { useEffect, useRef, useState, useCallback } from 'react';
 import { Link, useLocation, useNavigate } from 'react-router-dom';
 import {
+    AudioLines,
     BarChart3,
     Briefcase,
     Bug,
@@ -59,6 +60,12 @@ const NAV_ICONS = {
 // key. Module scope because two surfaces read it now: the header's action
 // chips and — when a project opts in — the sidebar's pinned action rows.
 const SETTING_ICONS = {
+    // A waveform, for recordings. `phone` is a handset and now belongs to the
+    // live Zoom Phone roster, which is a different question entirely — one chip
+    // is "listen to a call that happened", the other is "who is on a call right
+    // now", and two identical handsets in one header made them impossible to
+    // tell apart.
+    audioLines: AudioLines,
     bug: Bug,
     calendar: Calendar,
     key: KeyRound,
@@ -607,7 +614,9 @@ function Navigation({
                                             className={
                                                 cleanUrl(child.url) ===
                                                 bestMatchingUrl(
-                                                    n.children.map((one) => one.url),
+                                                    n.children.map(
+                                                        (one) => one.url
+                                                    ),
                                                     currentPage
                                                 )
                                                     ? styles.active

package/src/components/columns/SelectFilterEditor.jsx

@@ -0,0 +1,372 @@
+import { forwardRef, useImperativeHandle, useRef } from 'react';
+import SelectFilter from '@visns-studio/visns-datagrid-enterprise/SelectFilter';
+
+/**
+ * The grid's dropdown column filter, with one added behaviour: opening a
+ * filter that already holds a value clears that value.
+ *
+ * The complaint this answers is the everyday one — the Client filter says
+ * "Smith, John", you want a different client, and the only way to get a
+ * usable list is to hit the small × first, because the combo re-opens still
+ * carrying the old selection. Clicking the filter is already the gesture for
+ * "I want to choose again", so it now IS the clear: the chip disappears, the
+ * grid refilters as if the column were never filtered, and the menu you just
+ * opened shows the whole option list with an empty search box.
+ *
+ * ---------------------------------------------------------------------------
+ * Deliberate consequence: closing without picking leaves the filter CLEARED.
+ * There is no "restore what was there" on collapse — the click was the clear,
+ * and a filter that silently came back would make the gesture unpredictable.
+ * Re-picking the old option is one click away in the list that is already open.
+ *
+ * ---------------------------------------------------------------------------
+ * Only a DELIBERATE open clears — and that distinction has to be made here,
+ * because the combo expands on focus (`expandOnFocus`, on by default). Without
+ * the gate below, Tab-ing along the filter row would wipe every filled
+ * dropdown focus passed through, which is nobody's idea of "I clicked it".
+ * So an expand clears only when it followed, within a moment, either
+ *
+ *   - a pointer press inside this combo (a click on the field, its chip area
+ *     or its toggle arrow), or
+ *   - a key press inside this combo that means "open this / start searching"
+ *     (Enter, Space, Arrow Up/Down, F4, or a printable character).
+ *
+ * A Tab is neither: the keystroke lands on the element being left, so it is
+ * both the wrong key and outside this combo. Nothing else moves the needle —
+ * a programmatic focus, a saved view restoring a filter, or the grid's own
+ * focus handling all expand without a gesture and so leave the value alone.
+ *
+ * ---------------------------------------------------------------------------
+ * Why a wrapper and not a patch.
+ *
+ * `SelectFilter` lives in `@visns-studio/visns-datagrid-*` (the Inovua fork),
+ * which is vendor code we do not edit. Everything needed is reachable from
+ * outside it:
+ *
+ *   - `filterEditorProps` is spread straight onto the underlying `Combo`
+ *     (SelectFilter.render -> `finalProps`), so an `onExpandedChange` handed
+ *     down there is called by the combo on every expand and collapse —
+ *     mouse, keyboard and programmatic alike, since they all funnel through
+ *     `ComboBox.setExpanded()`. One interception point covers every way of
+ *     opening the list.
+ *   - The gesture behind an expand is not passed to `onExpandedChange`, and
+ *     the combo neither forwards `onClick`/`onMouseDown` (its own handlers
+ *     replace them on the root node) nor calls `props.onKeyDown` until after
+ *     it has already expanded. So the gesture is read from the page instead:
+ *     capture-phase `window` listeners record the last pointer/key press
+ *     before any React handler runs, and the expand asks what that was.
+ *   - The clear itself goes through the `SelectFilter` instance's own
+ *     `onChange`, which is exactly what the × button ends up calling: it drops
+ *     the displayed value and emits the emptied `filterValue` to the grid
+ *     (honouring `filterDelay`, as the × does). It deliberately does NOT go
+ *     through `Combo.setValue()`, which collapses the list when
+ *     `collapseOnSelect` is set — and SelectFilter always sets it, so clearing
+ *     that way would shut the menu the user just opened.
+ *
+ * The editor contract (props, the required `render` wrapper, the `setValue`
+ * the grid calls on the ref) is documented in NativeDateFilterEditor; this
+ * component forwards all of it to `SelectFilter` untouched.
+ */
+
+/**
+ * Filter editors are handed `filterEditorProps` both as a top-level prop and
+ * spread across their props (renderFilter/index.tsx `filterProps`), and it may
+ * be an object or a `(props) => object` factory — SelectFilter resolves it the
+ * same way.
+ */
+const resolveEditorProps = (props) => {
+    let { filterEditorProps } = props;
+
+    if (filterEditorProps === undefined) {
+        filterEditorProps =
+            props.filterValue && props.filterValue.filterEditorProps;
+    }
+
+    if (typeof filterEditorProps === 'function') {
+        return filterEditorProps(props) || {};
+    }
+
+    return filterEditorProps || {};
+};
+
+/**
+ * How long after a key or pointer press an expand still counts as that
+ * gesture's doing. A click expands in the same task; this is loose enough to
+ * survive a slow frame and far too tight to catch the next thing the user does.
+ */
+const GESTURE_WINDOW_MS = 700;
+
+/**
+ * Keys that mean "open this list", as opposed to Tab, which means "leave".
+ * A printable character counts too: typing into a filter is as deliberate as
+ * clicking it.
+ */
+const OPEN_KEYS = ['Enter', ' ', 'Spacebar', 'ArrowDown', 'ArrowUp', 'F4'];
+
+const isOpenKey = (event) => {
+    const { key } = event;
+
+    if (typeof key !== 'string' || key === 'Tab') {
+        return false;
+    }
+
+    if (OPEN_KEYS.indexOf(key) !== -1) {
+        return true;
+    }
+
+    return key.length === 1 && !event.ctrlKey && !event.metaKey;
+};
+
+/**
+ * The last user gesture seen anywhere on the page: `{ kind, target, at }`,
+ * where `kind` is 'open' for a press that means business and 'other' for
+ * everything else (a Tab, an Escape, a modifier).
+ */
+let lastGesture = null;
+let watching = false;
+
+/**
+ * One set of capture-phase listeners for the whole page, however many filters
+ * are on screen. Capture on `window` runs before React's delegated handlers,
+ * which is the point: the gesture is on record before the combo has decided to
+ * expand. They are passive and never removed — three listeners for the life of
+ * the page is cheaper than mounting and unmounting them per filter cell.
+ */
+const watchGestures = () => {
+    if (watching || typeof window === 'undefined') {
+        return;
+    }
+
+    watching = true;
+
+    const remember = (event, kind) => {
+        lastGesture = {
+            kind,
+            target: event.target,
+            at: Date.now(),
+        };
+    };
+
+    const options = { capture: true, passive: true };
+
+    window.addEventListener(
+        'mousedown',
+        (event) => remember(event, 'open'),
+        options
+    );
+    window.addEventListener(
+        'touchstart',
+        (event) => remember(event, 'open'),
+        options
+    );
+    window.addEventListener(
+        'keydown',
+        (event) => remember(event, isOpenKey(event) ? 'open' : 'other'),
+        options
+    );
+};
+
+/**
+ * Did the user just ask this combo to open, or did the combo open itself?
+ *
+ * `node` is the combo's own root element: a gesture outside it — the Tab press
+ * that lands on the element being left, a click elsewhere that moves focus —
+ * did not open this list, whatever else it did.
+ */
+export const openedByGesture = (
+    node,
+    gesture = lastGesture,
+    now = Date.now()
+) => {
+    if (!gesture || gesture.kind !== 'open' || !gesture.target) {
+        return false;
+    }
+
+    if (now - gesture.at > GESTURE_WINDOW_MS) {
+        return false;
+    }
+
+    return !!node && !!node.contains && node.contains(gesture.target);
+};
+
+/**
+ * "Is something actually filtered here?" — `null` is the `select` filter
+ * type's emptyValue, `''` is what DataGrid's dependent-filter reset writes,
+ * and a multi-select carries an array.
+ */
+export const hasFilterValue = (value) => {
+    if (value === null || value === undefined || value === '') {
+        return false;
+    }
+
+    if (Array.isArray(value)) {
+        return value.length > 0;
+    }
+
+    return true;
+};
+
+/**
+ * The whole decision, kept pure so it can be reasoned about (and tested)
+ * without a combo box.
+ *
+ * @param {boolean} expanded   the state the combo just moved to
+ * @param {boolean} openedDeliberately  the user opened it (see openedByGesture)
+ *                                      rather than focus opening it for them
+ * @param {*}       value      what the filter currently holds
+ * @param {boolean} multiple   multi-select (`operator: 'inlist'`)
+ * @param {boolean} clearOnOpen  per-column opt out (or opt in, for multiple)
+ * @param {boolean} disabled
+ * @param {boolean} readOnly
+ */
+export const shouldClearOnOpen = ({
+    expanded,
+    openedDeliberately,
+    value,
+    multiple,
+    clearOnOpen,
+    disabled,
+    readOnly,
+} = {}) => {
+    // Collapsing is not a clear, and an already-empty filter has nothing to
+    // clear — opening one must be a no-op so no needless refetch is posted.
+    if (!expanded || disabled || readOnly) {
+        return false;
+    }
+
+    // Focus alone expands the combo. That is not the user opening it, and
+    // clearing there would empty every filter a Tab travels past.
+    if (!openedDeliberately) {
+        return false;
+    }
+
+    if (clearOnOpen === false) {
+        return false;
+    }
+
+    // A multi-select is opened to ADD a choice as often as to replace one, so
+    // wiping the existing selections on open would make it impossible to pick
+    // a second value. Those columns keep the old behaviour unless a column
+    // explicitly asks for the clear with `filter.clearOnOpen: true`.
+    if (multiple && clearOnOpen !== true) {
+        return false;
+    }
+
+    return hasFilterValue(value);
+};
+
+const SelectFilterEditor = forwardRef((props, ref) => {
+    const { filterValue, emptyValue, onChange, disabled, readOnly } = props;
+
+    // Idempotent: the first filter cell on the page arms the listeners, the
+    // rest are no-ops. Done during render rather than in an effect so a combo
+    // that is clicked the instant it appears is already being watched.
+    watchGestures();
+
+    const innerRef = useRef(null);
+
+    // The grid reaches the editor through this ref: `GenericFilter.setValue`
+    // calls `setValue` on it (DataGrid's dependent-filter reset does exactly
+    // that), and `getInputRef` is read for focus handling. Both belong to the
+    // wrapped SelectFilter.
+    useImperativeHandle(
+        ref,
+        () => ({
+            setValue: (next) => {
+                if (innerRef.current && innerRef.current.setValue) {
+                    innerRef.current.setValue(next);
+                }
+            },
+            getInputRef: () =>
+                innerRef.current && innerRef.current.getInputRef
+                    ? innerRef.current.getInputRef()
+                    : null,
+        }),
+        []
+    );
+
+    // `null` is the `select` filter type's emptyValue (community-edition
+    // filterTypes.ts) and what the combo's × emits; fall back to it so a grid
+    // that does not pass the prop still clears to the same value.
+    const noValue = emptyValue === undefined ? null : emptyValue;
+
+    // Kept fresh on every render so the stable handler below always sees the
+    // current props without re-arming the combo's prop on each render.
+    const clearRef = useRef(null);
+    clearRef.current = (expanded) => {
+        const instance = innerRef.current;
+        const combo =
+            instance && instance.getInputRef && instance.getInputRef();
+        const editorProps = resolveEditorProps(props);
+
+        // The displayed value is SelectFilter's own state — with a
+        // `filterDelay` in play it is ahead of the `filterValue` prop, so it,
+        // not the prop, decides whether there is anything to clear.
+        const current =
+            instance && instance.state
+                ? instance.state.value
+                : filterValue && filterValue.value;
+
+        if (
+            !shouldClearOnOpen({
+                expanded,
+                openedDeliberately: openedByGesture(
+                    combo && combo.getComboNode ? combo.getComboNode() : null
+                ),
+                value: current,
+                multiple: editorProps.multiple,
+                clearOnOpen: editorProps.clearOnOpen,
+                disabled,
+                readOnly,
+            })
+        ) {
+            return;
+        }
+
+        if (instance && typeof instance.onChange === 'function') {
+            // The × button's path: drops the chip immediately and posts the
+            // emptied filter to the grid after `filterDelay`.
+            instance.onChange(noValue);
+        } else if (onChange) {
+            onChange({ ...filterValue, value: noValue });
+        }
+
+        // Leftover search text would filter the list the user is looking at.
+        // The combo normally clears it on select/blur, so this is a backstop;
+        // `skipFilter` avoids a redundant re-filter, and passing `null` (not
+        // `''`) keeps `clearValueOnEmpty` out of it — that path calls
+        // `Combo.setValue`, which would collapse the open menu.
+        if (combo && typeof combo.setText === 'function' && combo.getText()) {
+            combo.setText(null, { skipFilter: true });
+        }
+    };
+
+    const editorProps = resolveEditorProps(props);
+
+    // `clearOnOpen` is ours, not the combo's — and the combo hands every prop
+    // it does not recognise to a DOM node (`cleanProps` in ComboBox.render),
+    // which would put an unknown attribute on a div. Keep it out of what goes
+    // down.
+    const { clearOnOpen, ...comboProps } = editorProps;
+
+    return (
+        <SelectFilter
+            {...props}
+            ref={innerRef}
+            filterEditorProps={{
+                ...comboProps,
+                onExpandedChange: (expanded) => {
+                    if (editorProps.onExpandedChange) {
+                        editorProps.onExpandedChange(expanded);
+                    }
+
+                    clearRef.current(expanded);
+                },
+            }}
+        />
+    );
+});
+
+SelectFilterEditor.displayName = 'SelectFilterEditor';
+
+export default SelectFilterEditor;

package/src/components/controls/DataGridSearch.jsx

@@ -240,8 +240,13 @@ const DataGridSearch = ({
                 <div className={styles['icon-search']}>
                     <Search strokeWidth={2} size={14} />
                 </div>
+                {/* type="search", not "text": host apps style bare text inputs
+                    globally (throughlife's _forms.scss padded rule among them),
+                    and that padding put the magnifier on top of the placeholder.
+                    Search inputs are excluded from such rules, so the module's
+                    own matched icon-offset/indent pair applies. */}
                 <input
-                    type="text"
+                    type="search"
                     placeholder="Search"
                     value={search}
                     onChange={handleChangeSearch}

package/src/components/layout/AnchoredMenu.jsx

@@ -0,0 +1,131 @@
+import React, { useCallback, useEffect, useLayoutEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import styles from '../styles/AnchoredMenu.module.scss';
+
+/**
+ * The `⋯` menu on a row, rendered where nothing can clip it.
+ *
+ * Every list in this library's world had the same bug: the menu is
+ * `position: absolute` inside the row, the row is inside a card, and the card
+ * has `overflow: hidden` for its rounded corners — so on the LAST row of a band
+ * the menu was cut off entirely and the button looked like it did nothing. Give
+ * the list a scroll region (`ScrollRegion`) and it gets worse, because a
+ * scrolling ancestor clips too and now every row is the last row.
+ *
+ * There is no arrangement of `overflow` that fixes it, so the menu is not in the
+ * list at all: it is portalled to `document.body` and positioned `fixed` against
+ * the trigger's rectangle. Nothing between it and the viewport can clip it.
+ *
+ * IT CLOSES ON SCROLL rather than following the trigger. A menu that tracks a
+ * row while the list moves under it is more code and a worse idea — by the time
+ * it has travelled two hundred pixels the reader has lost which row it belongs
+ * to. Scrolling means "not that one", so it closes.
+ *
+ * @param {boolean} open       Whether the menu is showing.
+ * @param {Element} anchor     The trigger element to hang it off.
+ * @param {func}    onClose    Called on a click outside, Escape, or a scroll.
+ * @param {'start'|'end'} align  Which edge of the trigger it lines up with.
+ * @param {number}  gap        Space between the trigger and the menu.
+ * @param {string}  label      Accessible name for the menu.
+ */
+const AnchoredMenu = ({
+    open,
+    anchor,
+    onClose,
+    align = 'end',
+    gap = 4,
+    label = 'Actions',
+    className,
+    children,
+}) => {
+    const [position, setPosition] = useState(null);
+
+    const place = useCallback(() => {
+        if (!anchor) return;
+
+        const rect = anchor.getBoundingClientRect();
+
+        setPosition({
+            top: rect.bottom + gap,
+            left: align === 'end' ? null : rect.left,
+            right: align === 'end' ? window.innerWidth - rect.right : null,
+            // Enough room below? Otherwise flip above the trigger. Measured
+            // against a nominal menu height rather than the real one, which is
+            // not known until after it has been placed — and being 20px out on
+            // the decision is invisible, where a menu off the bottom of the
+            // window is not.
+            flip: window.innerHeight - rect.bottom < 180 && rect.top > 180,
+            anchorTop: rect.top,
+        });
+    }, [anchor, align, gap]);
+
+    useLayoutEffect(() => {
+        if (!open) {
+            setPosition(null);
+
+            return undefined;
+        }
+
+        place();
+
+        return undefined;
+    }, [open, place]);
+
+    useEffect(() => {
+        if (!open) return undefined;
+
+        const close = () => onClose?.();
+        const onKeyDown = (event) => {
+            if (event.key === 'Escape') close();
+        };
+
+        // Capture, so a scroll inside a list region closes it too — the event
+        // does not bubble from a scrolling element.
+        window.addEventListener('scroll', close, true);
+        window.addEventListener('resize', close);
+        window.addEventListener('keydown', onKeyDown);
+
+        return () => {
+            window.removeEventListener('scroll', close, true);
+            window.removeEventListener('resize', close);
+            window.removeEventListener('keydown', onKeyDown);
+        };
+    }, [open, onClose]);
+
+    if (!open || !position || typeof document === 'undefined') return null;
+
+    const style = {
+        top: position.flip ? undefined : position.top,
+        bottom: position.flip
+            ? window.innerHeight - position.anchorTop + gap
+            : undefined,
+        left: position.left ?? undefined,
+        right: position.right ?? undefined,
+    };
+
+    return createPortal(
+        <>
+            {/* A full-window hit target behind the menu, so one click anywhere
+                closes it however far the list has been scrolled. */}
+            <button
+                type="button"
+                className={styles.scrim}
+                aria-hidden="true"
+                tabIndex={-1}
+                onClick={() => onClose?.()}
+            />
+            <div
+                className={[styles.menu, className].filter(Boolean).join(' ')}
+                role="menu"
+                aria-label={label}
+                style={style}
+            >
+                {children}
+            </div>
+        </>,
+        document.body
+    );
+};
+
+export default AnchoredMenu;