@visns-studio/visns-components 6.5.4 → 6.6.0

package/src/components/utils/useDensity.js

@@ -0,0 +1,225 @@
+import { useMemo, useState, useEffect, useSyncExternalStore } from 'react';
+
+/**
+ * Display density, in JS.
+ *
+ * Two independent switches decide how roomy the UI is, and both live on the
+ * document rather than in React state, because both are set by whoever owns
+ * the page rather than by the component reading them:
+ *
+ *   - `data-density` on `<html>` — the app-wide opt-in, written by GenericAuth
+ *     from its `density` prop (see `styles/density.css` for the CSS half).
+ *   - `tablet-mode` on `<body>` — the per-view opt-in, written by GenericIndex
+ *     when a view config sets `"tabletMode": true`.
+ *
+ * They compose: a tablet view inside a large-density app is the roomiest of
+ * the four combinations. CSS reads both selectors directly; anything that has
+ * to lay out in JS — the datagrid measures and sizes rows in px — reads them
+ * through `useDensity()` so there is one table of numbers instead of a
+ * `isTabletMode ? 52 : 32` at every call site.
+ */
+
+/**
+ * The px geometry the datagrid cannot express in CSS.
+ *
+ * `default.desktop` / `default.tablet` are the values the grid has always
+ * used and must not drift — `tests/density.test.mjs` pins them.
+ *
+ *   rowHeight      fixed row height, or null to let the grid measure rows.
+ *   minRowHeight   floor applied to measured rows.
+ *   rowUnit        the height one row actually occupies, used to work out how
+ *                  many rows fit a page.
+ *   columnMinWidth floor for a column with no explicit `minWidth`.
+ *   actionColUnit  width one action icon needs inside an action column.
+ *   checkboxColWidth  fixed width of the row-select checkbox column.
+ */
+export const DENSITY_GRID = {
+    default: {
+        desktop: {
+            rowHeight: null,
+            minRowHeight: 32,
+            rowUnit: 32,
+            columnMinWidth: 80,
+            actionColUnit: 34,
+            checkboxColWidth: 60,
+        },
+        tablet: {
+            rowHeight: 52,
+            minRowHeight: 52,
+            rowUnit: 52,
+            columnMinWidth: 80,
+            actionColUnit: 44,
+            checkboxColWidth: 60,
+        },
+    },
+    large: {
+        desktop: {
+            rowHeight: null,
+            minRowHeight: 40,
+            rowUnit: 40,
+            columnMinWidth: 96,
+            actionColUnit: 44,
+            checkboxColWidth: 72,
+        },
+        tablet: {
+            rowHeight: 60,
+            minRowHeight: 60,
+            rowUnit: 60,
+            columnMinWidth: 96,
+            actionColUnit: 52,
+            checkboxColWidth: 80,
+        },
+    },
+};
+
+export const DEFAULT_DENSITY = 'default';
+
+const SERVER_SNAPSHOT = `${DEFAULT_DENSITY}|false`;
+
+/**
+ * Read both switches off the document as one string. A string (not an object)
+ * so `useSyncExternalStore` can compare snapshots by value — returning a fresh
+ * object from `getSnapshot` makes React re-render forever.
+ */
+const readSnapshot = () => {
+    if (typeof document === 'undefined') {
+        return SERVER_SNAPSHOT;
+    }
+
+    const density =
+        document.documentElement?.getAttribute('data-density') ||
+        DEFAULT_DENSITY;
+    const isTablet = Boolean(
+        document.body && document.body.classList.contains('tablet-mode')
+    );
+
+    return `${density}|${isTablet}`;
+};
+
+const getServerSnapshot = () => SERVER_SNAPSHOT;
+
+/**
+ * Notify on either switch changing. Two observers rather than one on the
+ * document, because we only care about one attribute on each of two nodes and
+ * a subtree observer would fire on every class change anywhere in the app.
+ */
+const subscribe = (onChange) => {
+    if (
+        typeof document === 'undefined' ||
+        typeof MutationObserver === 'undefined'
+    ) {
+        return () => {};
+    }
+
+    const observers = [];
+
+    if (document.documentElement) {
+        const rootObserver = new MutationObserver(onChange);
+        rootObserver.observe(document.documentElement, {
+            attributes: true,
+            attributeFilter: ['data-density'],
+        });
+        observers.push(rootObserver);
+    }
+
+    if (document.body) {
+        const bodyObserver = new MutationObserver(onChange);
+        bodyObserver.observe(document.body, {
+            attributes: true,
+            attributeFilter: ['class'],
+        });
+        observers.push(bodyObserver);
+    }
+
+    return () => observers.forEach((observer) => observer.disconnect());
+};
+
+/**
+ * Resolve a snapshot string into the shape callers want.
+ *
+ * @param {string} snapshot `"<density>|<isTabletMode>"`
+ * @returns {{density: string, isLarge: boolean, isTabletMode: boolean, grid: object}}
+ */
+export const parseDensitySnapshot = (snapshot) => {
+    const [rawDensity, rawTablet] = String(snapshot).split('|');
+    // An unrecognised attribute value styles as nothing in CSS, so it must
+    // measure as nothing here too.
+    const density = DENSITY_GRID[rawDensity] ? rawDensity : DEFAULT_DENSITY;
+    const isTabletMode = rawTablet === 'true';
+
+    return {
+        density,
+        isLarge: density === 'large',
+        isTabletMode,
+        grid: DENSITY_GRID[density][isTabletMode ? 'tablet' : 'desktop'],
+    };
+};
+
+/**
+ * @returns {{density: string, isLarge: boolean, isTabletMode: boolean, grid: object}}
+ *          `grid` is a stable reference out of `DENSITY_GRID`, so it is safe
+ *          in a dependency array.
+ */
+export const useDensity = () => {
+    const snapshot = useSyncExternalStore(
+        subscribe,
+        readSnapshot,
+        getServerSnapshot
+    );
+
+    return useMemo(() => parseDensitySnapshot(snapshot), [snapshot]);
+};
+
+/**
+ * Height left on screen below `ref`'s element, for panes that should fill the
+ * window instead of taking a fraction of it.
+ *
+ * Returns `null` until it can measure — no element, no window, or a
+ * measurement that comes out non-positive (the element is display:none, or
+ * scrolled out of view) — so callers can keep their own fallback rather than
+ * flashing a zero-height pane.
+ *
+ * @param {{current: HTMLElement|null}} ref     wrapper to measure from.
+ * @param {object}  [options]
+ * @param {boolean} [options.enabled=true]      false parks the hook at null.
+ * @param {number}  [options.bottomGutter=16]   px left below the element.
+ * @param {*}       [options.recomputeKey]      change it to force a re-measure
+ *                                              (e.g. the app's window height).
+ * @returns {number|null}
+ */
+export const useAvailableHeight = (
+    ref,
+    { enabled = true, bottomGutter = 16, recomputeKey } = {}
+) => {
+    const [height, setHeight] = useState(null);
+
+    useEffect(() => {
+        if (!enabled || typeof window === 'undefined') {
+            setHeight(null);
+            return undefined;
+        }
+
+        const measure = () => {
+            const node = ref?.current;
+
+            if (!node || typeof node.getBoundingClientRect !== 'function') {
+                setHeight(null);
+                return;
+            }
+
+            const { top } = node.getBoundingClientRect();
+            const next = window.innerHeight - top - bottomGutter;
+
+            setHeight(Number.isFinite(next) && next > 0 ? next : null);
+        };
+
+        measure();
+        window.addEventListener('resize', measure);
+
+        return () => window.removeEventListener('resize', measure);
+    }, [ref, enabled, bottomGutter, recomputeKey]);
+
+    return height;
+};
+
+export default useDensity;

package/src/index.js

@@ -7,6 +7,7 @@ import SortableList from './components/sorting/List';
 /** Utility Components */
 import { confirmDialog } from './components/utils/ConfirmDialog';
 import { showConfirmDialog } from './components/generic/ConfirmationDialog';
+import { useDensity, useAvailableHeight, DENSITY_GRID } from './components/utils/useDensity';
 
 /** CRM Components */
 import AsyncSelect from './components/AsyncSelect';
@@ -121,6 +122,7 @@ export {
     DataGrid,
     DataGridSearch,
     DatePickerPortal,
+    DENSITY_GRID,
     Download,
     DropZone,
     CategorizedDropZone,
@@ -173,6 +175,8 @@ export {
     StandardModal,
     Table,
     TableFilter,
+    useAvailableHeight,
+    useDensity,
     VariableInserter,
     Verify,
 };