@visns-studio/visns-components 6.20.1 → 6.23.0

package/src/components/layout/useContainedHeight.js

@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useState } from 'react';
+
+/**
+ * "Be as tall as whatever is left of the window, and scroll inside that."
+ *
+ * The problem it solves is not scrolling, it is LOSING THE CHROME. A list of
+ * four hundred clients scrolls the whole document, which takes the summary
+ * strip, the search box and the view tabs off the top of the screen — so
+ * finding a name and then narrowing the search means scrolling back up to
+ * controls that were in front of you a moment ago. Give the rows their own
+ * scroll region and everything above them stays put.
+ *
+ * WHY MEASURED RATHER THAN A CONSTANT. The obvious implementation is
+ * `max-height: calc(100vh - 22rem)` with the 22rem counted off the design. It
+ * is wrong on half the states of a real page: the strip has not loaded yet, a
+ * truncation notice appeared at a hundred rows, the header wrapped to two lines
+ * on a tablet. So the height is read from where the region actually starts —
+ * `getBoundingClientRect().top` — and recomputed whenever the window resizes or
+ * anything above it changes size.
+ *
+ * The `ResizeObserver` watches the region's PARENT rather than the region
+ * itself: the region's own height is the thing being set, and observing it
+ * would be a loop. What is wanted is "did the chrome above me move?", and the
+ * parent growing is the signal for that.
+ *
+ * Returns `null` until the first measurement, which is deliberate — a region
+ * rendered with no max-height for one frame is a page that is briefly too long,
+ * where one rendered at a guessed height is a page that visibly jumps.
+ *
+ * @param {object}  ref      Ref on the scrolling element.
+ * @param {number}  gutter   Space to leave under it, in pixels.
+ * @param {*}       deps     Anything that changes what is above it.
+ * @param {boolean} enabled  False leaves the height null and installs no
+ *                           listeners — for a component where the containment
+ *                           is opt-in and the hook still has to be called
+ *                           unconditionally.
+ */
+const useContainedHeight = (ref, gutter = 24, deps = null, enabled = true) => {
+    const [height, setHeight] = useState(null);
+
+    const measure = useCallback(() => {
+        const node = ref.current;
+
+        if (!enabled || !node || typeof window === 'undefined') return;
+
+        const top = node.getBoundingClientRect().top;
+        const available = window.innerHeight - top - gutter;
+
+        // A floor rather than a clamp to zero: on a short window the region
+        // still has to be usable, and 200px is about four rows.
+        setHeight(Math.max(available, 200));
+    }, [ref, gutter, enabled]);
+
+    useEffect(() => {
+        if (!enabled) return undefined;
+
+        measure();
+
+        window.addEventListener('resize', measure);
+
+        // Orientation changes on an iPad settle a beat after the event.
+        const settle = setTimeout(measure, 200);
+
+        let observer = null;
+
+        if (typeof ResizeObserver !== 'undefined' && ref.current?.parentElement) {
+            observer = new ResizeObserver(measure);
+            observer.observe(ref.current.parentElement);
+        }
+
+        return () => {
+            window.removeEventListener('resize', measure);
+            clearTimeout(settle);
+            if (observer) observer.disconnect();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [measure, deps, enabled]);
+
+    return height;
+};
+
+export default useContainedHeight;

package/src/components/navigation/TabStrip.jsx

@@ -0,0 +1,156 @@
+import React, { useCallback } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+import styles from '../styles/TabStrip.module.scss';
+
+/**
+ * react-router's search params, if there is a Router.
+ *
+ * Same shape and the same reasoning as `auth/useOptionalRouter`: the hook is
+ * called unconditionally on every render and only its throw is swallowed, which
+ * is what keeps this legal under the rules of hooks — whether a Router is above
+ * a component is fixed for that component's lifetime, so React never sees the
+ * hook count change.
+ *
+ * A strip used outside a Router simply cannot be URL-driven, and falls back to
+ * being controlled.
+ */
+const useOptionalSearchParams = () => {
+    try {
+        return useSearchParams();
+    } catch (error) {
+        // No Router above us. Expected wherever this is mounted outside an SPA.
+        return [null, null];
+    }
+};
+
+/**
+ * The underline tabs, driven either by the URL or by the caller.
+ *
+ * TWO MODES, and which one a page wants depends on whether the tab is a place.
+ *
+ *   CONTROLLED — pass `active` and `onChange`. The right answer when the tab is
+ *   a filter over the same page ("Active / Retired / All"): those are not
+ *   locations, and putting them in the URL invites somebody to bookmark a view
+ *   of a list rather than the list.
+ *
+ *   URL-DRIVEN — pass `param` (usually `'tab'`) and no `active`. The right
+ *   answer when the tab is a SECTION of a record: a deep link, a refresh and a
+ *   shared link all have to land in the same place. `replace` defaults to true
+ *   so five tab clicks do not become five back-button steps through a page
+ *   nobody ever left; a page whose tabs genuinely are separate destinations can
+ *   turn it off.
+ *
+ * Real `<button>`s in a tablist rather than links, in both modes: even when the
+ * tab is reflected in the URL, switching it is a state change rather than a
+ * navigation, and a router push per click fills the back button with noise.
+ *
+ * @param {Array}  tabs      `[{key, label, badge, badgeTone, disabled}]`.
+ * @param {string} active    Controlled mode: the current key.
+ * @param {func}   onChange  Called with the key. Fires in URL mode too, so a
+ *                           page can invalidate a cache on the way past.
+ * @param {string} param     URL mode: the search param that owns the tab.
+ * @param {bool}   replace   URL mode: replace rather than push. Default true.
+ * @param {string} fallback  What an unrecognised (or absent) param means.
+ *                           Defaults to the first tab.
+ * @param {'quiet'|'danger'} badgeTone  Default tone for every badge.
+ */
+const TabStrip = ({
+    tabs = [],
+    active,
+    onChange,
+    param,
+    replace = true,
+    fallback,
+    ariaLabel = 'Sections',
+    badgeTone = 'quiet',
+    className,
+    tabClassName,
+    ...rest
+}) => {
+    const [searchParams, setSearchParams] = useOptionalSearchParams();
+
+    const urlDriven = Boolean(param) && searchParams !== null && active === undefined;
+
+    const known = (key) => tabs.some((tab) => tab.key === key);
+    const defaultKey = fallback ?? tabs[0]?.key;
+
+    let current = active;
+
+    if (urlDriven) {
+        const requested = searchParams.get(param);
+
+        current = known(requested) ? requested : defaultKey;
+    }
+
+    const select = useCallback(
+        (key) => {
+            if (urlDriven) {
+                setSearchParams(
+                    (params) => {
+                        const next = new URLSearchParams(params);
+
+                        next.set(param, key);
+
+                        return next;
+                    },
+                    { replace }
+                );
+            }
+
+            if (onChange) onChange(key);
+        },
+        [urlDriven, setSearchParams, param, replace, onChange]
+    );
+
+    if (tabs.length === 0) return null;
+
+    return (
+        <div
+            className={[styles.strip, className].filter(Boolean).join(' ')}
+            role="tablist"
+            aria-label={ariaLabel}
+            {...rest}
+        >
+            {tabs.map((tab) => {
+                const selected = current === tab.key;
+                const tone = tab.badgeTone ?? badgeTone;
+
+                return (
+                    <button
+                        key={tab.key}
+                        type="button"
+                        role="tab"
+                        aria-selected={selected}
+                        disabled={tab.disabled}
+                        className={[
+                            styles.tab,
+                            selected ? styles.active : null,
+                            tabClassName,
+                        ]
+                            .filter(Boolean)
+                            .join(' ')}
+                        onClick={() => select(tab.key)}
+                    >
+                        {tab.label}
+
+                        {tab.badge ? (
+                            <span
+                                className={[
+                                    styles.badge,
+                                    tone === 'danger'
+                                        ? styles.badgeDanger
+                                        : styles.badgeQuiet,
+                                ].join(' ')}
+                            >
+                                {tab.badge}
+                            </span>
+                        ) : null}
+                    </button>
+                );
+            })}
+        </div>
+    );
+};
+
+export default TabStrip;