@homebound/beam 2.135.2 → 2.137.0

package/dist/components/AutoSaveIndicator.d.ts

@@ -0,0 +1,6 @@
+interface AutoSaveIndicatorProps {
+    hideOnIdle?: boolean;
+    doNotReset?: boolean;
+}
+export declare function AutoSaveIndicator({ hideOnIdle, doNotReset }: AutoSaveIndicatorProps): import("@emotion/react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/AutoSaveIndicator.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutoSaveIndicator = void 0;
+const jsx_runtime_1 = require("@emotion/react/jsx-runtime");
+const form_state_1 = require("@homebound/form-state");
+const react_1 = require("react");
+const Css_1 = require("../Css");
+const types_1 = require("../types");
+const _1 = require(".");
+const Icon_1 = require("./Icon");
+function AutoSaveIndicator({ hideOnIdle, doNotReset }) {
+    const { status, resetStatus, errors } = (0, form_state_1.useAutoSaveStatus)();
+    (0, react_1.useEffect)(() => {
+        if (doNotReset)
+            return;
+        /**
+         * Any time AutoSaveIndicator dismounts, most likely on Page Navigation,
+         * state should clear before the next Indicator mounts
+         */
+        return () => resetStatus();
+    }, []);
+    switch (status) {
+        case form_state_1.AutoSaveStatus.IDLE:
+            return hideOnIdle ? null : (0, jsx_runtime_1.jsx)(Icon_1.Icon, { icon: "cloudSave", color: Css_1.Palette.Gray700 }, void 0);
+        case form_state_1.AutoSaveStatus.SAVING:
+            return ((0, jsx_runtime_1.jsx)(HelperText, Object.assign({ text: "Saving...", color: Css_1.Palette.Gray700 }, { children: (0, jsx_runtime_1.jsx)(Icon_1.Icon, { icon: "refresh", color: Css_1.Palette.Gray700 }, void 0) }), void 0));
+        case form_state_1.AutoSaveStatus.DONE:
+            return ((0, jsx_runtime_1.jsx)(HelperText, Object.assign({ text: "Saved", color: Css_1.Palette.LightBlue700 }, { children: (0, jsx_runtime_1.jsx)(Icon_1.Icon, { icon: "cloudSave", color: Css_1.Palette.LightBlue700 }, void 0) }), void 0));
+        case form_state_1.AutoSaveStatus.ERROR:
+            return (
+            /**
+             * Tooltip is expanding to fill as much available space as it can, possibly
+             * rendering it far away from the Icon/Text. Wrap it with a div to constrain
+             * it.
+             */
+            (0, jsx_runtime_1.jsx)("div", Object.assign({ css: Css_1.Css.dif.$ }, { children: (0, jsx_runtime_1.jsx)(_1.Tooltip, Object.assign({ title: String(errors), placement: "bottom" }, { children: (0, jsx_runtime_1.jsx)(HelperText, Object.assign({ text: "Error saving", color: Css_1.Palette.Gray700 }, { children: (0, jsx_runtime_1.jsx)(Icon_1.Icon, { icon: "error", color: Css_1.Palette.Red500 }, void 0) }), void 0) }), void 0) }), void 0));
+        default:
+            (0, types_1.assertNever)(status);
+    }
+}
+exports.AutoSaveIndicator = AutoSaveIndicator;
+const HelperText = ({ text, color, children }) => ((0, jsx_runtime_1.jsxs)("div", Object.assign({ css: Css_1.Css.df.gap1.color(color).$ }, { children: [children, text] }), void 0));

package/dist/components/BeamContext.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useBeamContext = exports.BeamProvider = exports.BeamContext = void 0;
 const jsx_runtime_1 = require("@emotion/react/jsx-runtime");
+const form_state_1 = require("@homebound/form-state");
 const react_1 = require("react");
 const react_aria_1 = require("react-aria");
 const Modal_1 = require("./Modal/Modal");
@@ -56,7 +57,7 @@ function BeamProvider({ children, ...presentationProps }) {
             tabActionsDiv,
         };
     }, [modalBodyDiv, modalFooterDiv]);
-    return ((0, jsx_runtime_1.jsx)(exports.BeamContext.Provider, Object.assign({ value: { ...context } }, { children: (0, jsx_runtime_1.jsx)(PresentationContext_1.PresentationProvider, Object.assign({}, presentationProps, { children: (0, jsx_runtime_1.jsxs)(SnackbarContext_1.SnackbarProvider, { children: [(0, jsx_runtime_1.jsxs)(react_aria_1.OverlayProvider, { children: [children, modalRef.current && drawerContentStackRef.current.length === 0 && (0, jsx_runtime_1.jsx)(Modal_1.Modal, Object.assign({}, modalRef.current), void 0)] }, void 0), (0, jsx_runtime_1.jsx)(SuperDrawer_1.SuperDrawer, {}, void 0)] }, void 0) }), void 0) }), void 0));
+    return ((0, jsx_runtime_1.jsx)(exports.BeamContext.Provider, Object.assign({ value: { ...context } }, { children: (0, jsx_runtime_1.jsx)(PresentationContext_1.PresentationProvider, Object.assign({}, presentationProps, { children: (0, jsx_runtime_1.jsx)(form_state_1.AutoSaveStatusProvider, { children: (0, jsx_runtime_1.jsxs)(SnackbarContext_1.SnackbarProvider, { children: [(0, jsx_runtime_1.jsxs)(react_aria_1.OverlayProvider, { children: [children, modalRef.current && drawerContentStackRef.current.length === 0 && (0, jsx_runtime_1.jsx)(Modal_1.Modal, Object.assign({}, modalRef.current), void 0)] }, void 0), (0, jsx_runtime_1.jsx)(SuperDrawer_1.SuperDrawer, {}, void 0)] }, void 0) }, void 0) }), void 0) }), void 0));
 }
 exports.BeamProvider = BeamProvider;
 /** Looks like a ref, but invokes a re-render on set (w/o changing the setter identity). */

package/dist/components/Filters/Filters.js

@@ -29,7 +29,7 @@ function Filters(props) {
         return [Object.fromEntries(impls), {}];
     }, [numberOfPageFilters, filterDefs]);
     const numModalFilters = (0, utils_1.safeKeys)(modalFilters).filter((fk) => filter[fk] !== undefined).length;
-    const maybeGroupByField = groupBy ? ((0, jsx_runtime_1.jsx)("div", { children: (0, jsx_runtime_1.jsx)(SelectField_1.SelectField, { label: "Group by", compact: !vertical, inlineLabel: !vertical, sizeToContent: !vertical, options: groupBy.options, getOptionValue: (o) => o.id, getOptionLabel: (o) => o.name, value: groupBy.value, onSelect: (g) => groupBy.setValue(g) }, void 0) }, void 0)) : null;
+    const maybeGroupByField = groupBy ? ((0, jsx_runtime_1.jsx)("div", { children: (0, jsx_runtime_1.jsx)(SelectField_1.SelectField, { label: "Group by", compact: !vertical, inlineLabel: !vertical, sizeToContent: !vertical, options: groupBy.options, getOptionValue: (o) => o.id, getOptionLabel: (o) => o.name, value: groupBy.value, onSelect: (g) => g && groupBy.setValue(g) }, void 0) }, void 0)) : null;
     // Return list of filter components. `onSelect` should update the `filter`
     return ((0, jsx_runtime_1.jsxs)("div", Object.assign({ css: {
             ...(vertical ? Css_1.Css.df.fdc.childGap2.$ : Css_1.Css.df.aic.childGap1.$),

package/dist/components/Modal/Modal.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ModalFooter = exports.ModalBody = exports.ModalHeader = exports.Modal = void 0;
 const jsx_runtime_1 = require("@emotion/react/jsx-runtime");
+const form_state_1 = require("@homebound/form-state");
 const resize_observer_1 = __importDefault(require("@react-hook/resize-observer"));
 const react_1 = require("react");
 const react_aria_1 = require("react-aria");
@@ -64,12 +65,12 @@ function Modal(props) {
         modalBodyRef.current.appendChild(modalBodyDiv);
         modalFooterRef.current.appendChild(modalFooterDiv);
     }, [modalBodyRef, modalFooterRef, modalHeaderRef]);
-    return ((0, jsx_runtime_1.jsx)(react_aria_1.OverlayContainer, { children: (0, jsx_runtime_1.jsx)("div", Object.assign({ css: Css_1.Css.underlay.z4.$ }, underlayProps, testId.underlay, { children: (0, jsx_runtime_1.jsx)(react_aria_1.FocusScope, Object.assign({ contain: true, restoreFocus: true, autoFocus: true }, { children: (0, jsx_runtime_1.jsxs)("div", Object.assign({ css: Css_1.Css.br24.bgWhite.bshModal.overflowHidden
-                        .maxh("90vh")
-                        .df.fdc.wPx(width)
-                        .mh((0, Css_1.px)(defaultMinHeight))
-                        .if(isFixedHeight)
-                        .hPx(height).$, ref: ref }, overlayProps, dialogProps, modalProps, testId, { children: [(0, jsx_runtime_1.jsxs)("header", Object.assign({ css: Css_1.Css.df.p3.fs0.if(drawHeaderBorder).bb.bGray200.$ }, { children: [(0, jsx_runtime_1.jsx)("h1", Object.assign({ css: Css_1.Css.fg1.xl2Em.gray900.$, ref: modalHeaderRef }, titleProps, testId.title), void 0), (0, jsx_runtime_1.jsx)("span", Object.assign({ css: Css_1.Css.fs0.pl1.$ }, { children: (0, jsx_runtime_1.jsx)(IconButton_1.IconButton, Object.assign({ icon: "x", onClick: closeModal }, testId.titleClose), void 0) }), void 0)] }), void 0), (0, jsx_runtime_1.jsxs)("main", Object.assign({ ref: contentRef, css: Css_1.Css.fg1.overflowYAuto.if(hasScroll).bb.bGray200.if(!!forceScrolling).overflowYScroll.$ }, { children: [content, (0, jsx_runtime_1.jsx)("div", { ref: modalBodyRef }, void 0)] }), void 0), (0, jsx_runtime_1.jsx)("footer", Object.assign({ css: Css_1.Css.fs0.$ }, { children: (0, jsx_runtime_1.jsx)("div", { ref: modalFooterRef }, void 0) }), void 0)] }), void 0) }), void 0) }), void 0) }, void 0));
+    return ((0, jsx_runtime_1.jsx)(react_aria_1.OverlayContainer, { children: (0, jsx_runtime_1.jsx)(form_state_1.AutoSaveStatusProvider, { children: (0, jsx_runtime_1.jsx)("div", Object.assign({ css: Css_1.Css.underlay.z4.$ }, underlayProps, testId.underlay, { children: (0, jsx_runtime_1.jsx)(react_aria_1.FocusScope, Object.assign({ contain: true, restoreFocus: true, autoFocus: true }, { children: (0, jsx_runtime_1.jsxs)("div", Object.assign({ css: Css_1.Css.br24.bgWhite.bshModal.overflowHidden
+                            .maxh("90vh")
+                            .df.fdc.wPx(width)
+                            .mh((0, Css_1.px)(defaultMinHeight))
+                            .if(isFixedHeight)
+                            .hPx(height).$, ref: ref }, overlayProps, dialogProps, modalProps, testId, { children: [(0, jsx_runtime_1.jsxs)("header", Object.assign({ css: Css_1.Css.df.p3.fs0.if(drawHeaderBorder).bb.bGray200.$ }, { children: [(0, jsx_runtime_1.jsx)("h1", Object.assign({ css: Css_1.Css.fg1.xl2Em.gray900.$, ref: modalHeaderRef }, titleProps, testId.title), void 0), (0, jsx_runtime_1.jsx)("span", Object.assign({ css: Css_1.Css.fs0.pl1.$ }, { children: (0, jsx_runtime_1.jsx)(IconButton_1.IconButton, Object.assign({ icon: "x", onClick: closeModal }, testId.titleClose), void 0) }), void 0)] }), void 0), (0, jsx_runtime_1.jsxs)("main", Object.assign({ ref: contentRef, css: Css_1.Css.fg1.overflowYAuto.if(hasScroll).bb.bGray200.if(!!forceScrolling).overflowYScroll.$ }, { children: [content, (0, jsx_runtime_1.jsx)("div", { ref: modalBodyRef }, void 0)] }), void 0), (0, jsx_runtime_1.jsx)("footer", Object.assign({ css: Css_1.Css.fs0.$ }, { children: (0, jsx_runtime_1.jsx)("div", { ref: modalFooterRef }, void 0) }), void 0)] }), void 0) }), void 0) }), void 0) }, void 0) }, void 0));
 }
 exports.Modal = Modal;
 function ModalHeader({ children }) {

package/dist/components/SuperDrawer/SuperDrawer.js

@@ -4,6 +4,7 @@ exports.SuperDrawer = void 0;
 const react_1 = require("@emotion/react");
 const jsx_runtime_1 = require("@emotion/react/jsx-runtime");
 const react_2 = require("@emotion/react");
+const form_state_1 = require("@homebound/form-state");
 const framer_motion_1 = require("framer-motion");
 const react_3 = require("react");
 const react_dom_1 = require("react-dom");
@@ -71,29 +72,29 @@ function SuperDrawer() {
                     animate: { opacity: 1 }, 
                     // Unmount styles
                     exit: { opacity: 0, transition: { delay: 0.2 } }, onClick: closeDrawer },
-                    (0, jsx_runtime_1.jsxs)(framer_motion_1.motion.aside, Object.assign({ css: Css_1.Css.bgWhite.h100.maxw((0, Css_1.px)(1040)).w100.df.fdc.relative.$, 
+                    (0, jsx_runtime_1.jsx)(framer_motion_1.motion.aside, Object.assign({ css: Css_1.Css.bgWhite.h100.maxw((0, Css_1.px)(1040)).w100.df.fdc.relative.$, 
                         // Keeping initial x to 1040 as this will still work if the container is smaller
                         initial: { x: 1040 }, animate: { x: 0 }, 
                         // Custom transitions settings for the translateX animation
                         transition: { ease: "linear", duration: 0.2, delay: 0.2 }, exit: { transition: { ease: "linear", duration: 0.2 }, x: 1040 }, 
                         // Preventing clicks from triggering parent onClick
-                        onClick: (e) => e.stopPropagation() }, { children: [(0, jsx_runtime_1.jsxs)("header", Object.assign({ css: Css_1.Css.df.p3.bb.bGray200.df.aic.jcsb.gap2.$ }, { children: [(0, jsx_runtime_1.jsxs)("div", Object.assign({ css: Css_1.Css.df.aic.$ }, { children: [(0, jsx_runtime_1.jsx)("div", Object.assign({ css: Css_1.Css.xl2Em.gray900.mr2.$ }, testId.title, { ref: drawerHeaderRef }, { children: !modalState.current && (title || null) }), void 0), !modalState.current && (titleLeftContent || null)] }), void 0), !modalState.current && (
-                                    // Forcing height to 32px to match title height
-                                    (0, jsx_runtime_1.jsxs)("div", Object.assign({ css: Css_1.Css.df.childGap3.aic.hPx(32).fs0.$ }, { children: [titleRightContent || null, (0, jsx_runtime_1.jsx)(components_1.ButtonGroup, Object.assign({ buttons: [
-                                                    {
-                                                        icon: "chevronLeft",
-                                                        onClick: () => onPrevClick && onPrevClick(),
-                                                        disabled: !onPrevClick || isDetail,
-                                                    },
-                                                    {
-                                                        icon: "chevronRight",
-                                                        onClick: () => onNextClick && onNextClick(),
-                                                        disabled: !onNextClick || isDetail,
-                                                    },
-                                                ] }, testId.headerActions), void 0), (0, jsx_runtime_1.jsx)(components_1.IconButton, Object.assign({ icon: "x", onClick: closeDrawer }, testId.close), void 0)] }), void 0))] }), void 0), content, modalState.current && (
-                            // Forcing some design constraints on the modal component
-                            (0, jsx_runtime_1.jsxs)("div", Object.assign({ css: 
-                                // topPX(81) is the offset from the header
-                                Css_1.Css.fg1.topPx(81).left0.right0.bottom0.absolute.bgWhite.df.aic.jcc.fg1.fdc.z5.$ }, { children: [modalState.current.content, (0, jsx_runtime_1.jsx)("div", { ref: modalBodyRef }, void 0), (0, jsx_runtime_1.jsx)("div", { ref: modalFooterRef }, void 0)] }), void 0))] }), "superDrawerContainer"))] }, void 0)) }, void 0), document.body);
+                        onClick: (e) => e.stopPropagation() }, { children: (0, jsx_runtime_1.jsxs)(form_state_1.AutoSaveStatusProvider, { children: [(0, jsx_runtime_1.jsxs)("header", Object.assign({ css: Css_1.Css.df.p3.bb.bGray200.df.aic.jcsb.gap2.$ }, { children: [(0, jsx_runtime_1.jsxs)("div", Object.assign({ css: Css_1.Css.df.aic.$ }, { children: [(0, jsx_runtime_1.jsx)("div", Object.assign({ css: Css_1.Css.xl2Em.gray900.mr2.$ }, testId.title, { ref: drawerHeaderRef }, { children: !modalState.current && (title || null) }), void 0), !modalState.current && (titleLeftContent || null)] }), void 0), !modalState.current && (
+                                        // Forcing height to 32px to match title height
+                                        (0, jsx_runtime_1.jsxs)("div", Object.assign({ css: Css_1.Css.df.childGap3.aic.hPx(32).fs0.$ }, { children: [titleRightContent || null, (0, jsx_runtime_1.jsx)(components_1.ButtonGroup, Object.assign({ buttons: [
+                                                        {
+                                                            icon: "chevronLeft",
+                                                            onClick: () => onPrevClick && onPrevClick(),
+                                                            disabled: !onPrevClick || isDetail,
+                                                        },
+                                                        {
+                                                            icon: "chevronRight",
+                                                            onClick: () => onNextClick && onNextClick(),
+                                                            disabled: !onNextClick || isDetail,
+                                                        },
+                                                    ] }, testId.headerActions), void 0), (0, jsx_runtime_1.jsx)(components_1.IconButton, Object.assign({ icon: "x", onClick: closeDrawer }, testId.close), void 0)] }), void 0))] }), void 0), content, modalState.current && (
+                                // Forcing some design constraints on the modal component
+                                (0, jsx_runtime_1.jsxs)("div", Object.assign({ css: 
+                                    // topPX(81) is the offset from the header
+                                    Css_1.Css.fg1.topPx(81).left0.right0.bottom0.absolute.bgWhite.df.aic.jcc.fg1.fdc.z5.$ }, { children: [modalState.current.content, (0, jsx_runtime_1.jsx)("div", { ref: modalBodyRef }, void 0), (0, jsx_runtime_1.jsx)("div", { ref: modalFooterRef }, void 0)] }), void 0))] }, void 0) }), "superDrawerContainer"))] }, void 0)) }, void 0), document.body);
 }
 exports.SuperDrawer = SuperDrawer;

package/dist/components/Table/GridTable.js

@@ -140,8 +140,8 @@ function GridTable(props) {
         }
         else {
             // Otherwise, maybe one of the children match.
-            const isCollapsed = collapsedIds.includes(row.id);
-            if (!isCollapsed && !!((_c = row.children) === null || _c === void 0 ? void 0 : _c.length)) {
+            // Always filter children rows whether or not they are collapsed in order to determine proper "selected" state of the group row.
+            if (!!((_c = row.children) === null || _c === void 0 ? void 0 : _c.length)) {
                 const matchedChildren = row.children.reduce(filterRows, []);
                 // If some children did match, then add the parent row with its matched children.
                 if (matchedChildren.length > 0) {
@@ -152,7 +152,7 @@ function GridTable(props) {
         return acc;
     }, [filter, collapsedIds, columns]);
     // Flatten + component-ize the sorted rows.
-    let [headerRows, filteredRows, totalsRows] = (0, react_1.useMemo)(() => {
+    let [headerRows, visibleDataRows, totalsRows, filteredRowIds] = (0, react_1.useMemo)(() => {
         function makeRowComponent(row, level) {
             // We only pass sortState to header rows, b/c non-headers rows shouldn't have to re-render on sorting
             // changes, and so by not passing the sortProps, it means the data rows' React.memo will still cache them.
@@ -178,20 +178,25 @@ function GridTable(props) {
         // Split out the header rows from the data rows so that we can put an `infoMessage` in between them (if needed).
         const headerRows = [];
         const totalsRows = [];
-        const filteredRows = [];
+        const visibleDataRows = [];
+        const filteredRowIds = [];
         // Misc state to track our nested card-ification, i.e. interleaved actual rows + chrome rows
-        const nestedCards = !!style.nestedCards && new nestedCards_1.NestedCards(columns, filteredRows, style.nestedCards);
-        function visit([row, children], level) {
-            let isCard = nestedCards && nestedCards.maybeOpenCard(row);
-            filteredRows.push([row, makeRowComponent(row, level)]);
-            const isCollapsed = collapsedIds.includes(row.id);
-            if (!isCollapsed && children.length) {
-                nestedCards && nestedCards.addSpacer();
-                visitRows(children, isCard, level + 1);
+        const nestedCards = !!style.nestedCards && new nestedCards_1.NestedCards(columns, visibleDataRows, style.nestedCards);
+        function visit([row, children], level, visible) {
+            let isCard = visible && nestedCards && nestedCards.maybeOpenCard(row);
+            visible && visibleDataRows.push([row, makeRowComponent(row, level)]);
+            // This row may be invisible (because it's parent is collapsed), but we still want
+            // to consider it matched if it or it's parent matched a filter.
+            filteredRowIds.push(row.id);
+            if (children.length) {
+                // Consider "isCollapsed" as true if the parent wasn't visible.
+                const isCollapsed = !visible || collapsedIds.includes(row.id);
+                !isCollapsed && nestedCards && nestedCards.addSpacer();
+                visitRows(children, isCard, level + 1, !isCollapsed);
             }
-            !(0, nestedCards_1.isLeafRow)(row) && isCard && nestedCards && nestedCards.closeCard();
+            visible && !(0, nestedCards_1.isLeafRow)(row) && isCard && nestedCards && nestedCards.closeCard();
         }
-        function visitRows(rows, addSpacer, level) {
+        function visitRows(rows, addSpacer, level, visible) {
             const length = rows.length;
             rows.forEach((row, i) => {
                 if (row[0].kind === "header") {
@@ -202,15 +207,15 @@ function GridTable(props) {
                     totalsRows.push([row[0], makeRowComponent(row[0], level)]);
                     return;
                 }
-                visit(row, level);
-                addSpacer && nestedCards && i !== length - 1 && nestedCards.addSpacer();
+                visit(row, level, visible);
+                visible && addSpacer && nestedCards && i !== length - 1 && nestedCards.addSpacer();
             });
         }
         // Call `visitRows` with our a pre-filtered set list
         // If nestedCards is set, we assume the top-level kind is a card, and so should add spacers between them
-        visitRows(maybeSorted.reduce(filterRows, []), !!nestedCards, 0);
+        visitRows(maybeSorted.reduce(filterRows, []), !!nestedCards, 0, true);
         nestedCards && nestedCards.done();
-        return [headerRows, filteredRows, totalsRows];
+        return [headerRows, visibleDataRows, totalsRows, filteredRowIds];
     }, [
         as,
         maybeSorted,
@@ -230,21 +235,21 @@ function GridTable(props) {
         hasTotalsRow,
     ]);
     let tooManyClientSideRows = false;
-    if (filterMaxRows && filteredRows.length > filterMaxRows) {
+    if (filterMaxRows && visibleDataRows.length > filterMaxRows) {
         tooManyClientSideRows = true;
-        filteredRows = filteredRows.slice(0, filterMaxRows);
+        visibleDataRows = visibleDataRows.slice(0, filterMaxRows);
     }
-    rowState.setVisibleRows(filteredRows.map(([row]) => { var _a; return (_a = row === null || row === void 0 ? void 0 : row.id) !== null && _a !== void 0 ? _a : ""; }));
+    rowState.setMatchedRows(filteredRowIds);
     // Push back to the caller a way to ask us where a row is.
     const { rowLookup } = props;
     if (rowLookup) {
         // Refs are cheap to assign to, so we don't bother doing this in a useEffect
-        rowLookup.current = (0, GridRowLookup_1.createRowLookup)(columns, filteredRows, virtuosoRef);
+        rowLookup.current = (0, GridRowLookup_1.createRowLookup)(columns, visibleDataRows, virtuosoRef);
     }
     (0, react_1.useEffect)(() => {
-        setRowCount && (filteredRows === null || filteredRows === void 0 ? void 0 : filteredRows.length) !== undefined && setRowCount(filteredRows.length);
-    }, [filteredRows === null || filteredRows === void 0 ? void 0 : filteredRows.length, setRowCount]);
-    const noData = filteredRows.length === 0;
+        setRowCount && (visibleDataRows === null || visibleDataRows === void 0 ? void 0 : visibleDataRows.length) !== undefined && setRowCount(visibleDataRows.length);
+    }, [visibleDataRows === null || visibleDataRows === void 0 ? void 0 : visibleDataRows.length, setRowCount]);
+    const noData = visibleDataRows.length === 0;
     const firstRowMessage = (noData && fallbackMessage) || (tooManyClientSideRows && "Hiding some rows, use filter...") || infoMessage;
     const borderless = (_a = style === null || style === void 0 ? void 0 : style.presentationSettings) === null || _a === void 0 ? void 0 : _a.borderless;
     const typeScale = (_b = style === null || style === void 0 ? void 0 : style.presentationSettings) === null || _b === void 0 ? void 0 : _b.typeScale;
@@ -263,7 +268,7 @@ function GridTable(props) {
     // behave semantically the same as `as=div` did for its tests.
     const _as = as === "virtual" && runningInJest ? "div" : as;
     const rowStateContext = (0, react_1.useMemo)(() => ({ rowState }), [rowState]);
-    return ((0, jsx_runtime_1.jsx)(RowState_1.RowStateContext.Provider, Object.assign({ value: rowStateContext }, { children: (0, jsx_runtime_1.jsxs)(PresentationContext_1.PresentationProvider, Object.assign({ fieldProps: fieldProps, wrap: (_c = style === null || style === void 0 ? void 0 : style.presentationSettings) === null || _c === void 0 ? void 0 : _c.wrap }, { children: [(0, jsx_runtime_1.jsx)("div", { ref: resizeRef, css: Css_1.Css.w100.$ }, void 0), renders[_as](style, id, columns, headerRows, totalsRows, filteredRows, firstRowMessage, stickyHeader, (_d = style.nestedCards) === null || _d === void 0 ? void 0 : _d.firstLastColumnWidth, xss, virtuosoRef)] }), void 0) }), void 0));
+    return ((0, jsx_runtime_1.jsx)(RowState_1.RowStateContext.Provider, Object.assign({ value: rowStateContext }, { children: (0, jsx_runtime_1.jsxs)(PresentationContext_1.PresentationProvider, Object.assign({ fieldProps: fieldProps, wrap: (_c = style === null || style === void 0 ? void 0 : style.presentationSettings) === null || _c === void 0 ? void 0 : _c.wrap }, { children: [(0, jsx_runtime_1.jsx)("div", { ref: resizeRef, css: Css_1.Css.w100.$ }, void 0), renders[_as](style, id, columns, headerRows, totalsRows, visibleDataRows, firstRowMessage, stickyHeader, (_d = style.nestedCards) === null || _d === void 0 ? void 0 : _d.firstLastColumnWidth, xss, virtuosoRef)] }), void 0) }), void 0));
 }
 exports.GridTable = GridTable;
 // Determine which HTML element to use to build the GridTable
@@ -273,7 +278,7 @@ const renders = {
     virtual: renderVirtual,
 };
 /** Renders table using divs with flexbox rows, which is the default render */
-function renderDiv(style, id, columns, headerRows, totalsRows, filteredRows, firstRowMessage, _stickyHeader, firstLastColumnWidth, xss, _virtuosoRef) {
+function renderDiv(style, id, columns, headerRows, totalsRows, visibleDataRows, firstRowMessage, _stickyHeader, firstLastColumnWidth, xss, _virtuosoRef) {
     return ((0, jsx_runtime_1.jsxs)("div", Object.assign({ css: {
             // Use `fit-content` to ensure the width of the table takes up the full width of its content.
             // Otherwise, the table's width would be that of its container, which may not be as wide as the table itself.
@@ -290,10 +295,10 @@ function renderDiv(style, id, columns, headerRows, totalsRows, filteredRows, fir
             ...style.rootCss,
             ...(style.minWidthPx ? Css_1.Css.mwPx(style.minWidthPx).$ : {}),
             ...xss,
-        }, "data-testid": id }, { children: [totalsRows.map(([, node]) => node), headerRows.map(([, node]) => node), firstRowMessage && ((0, jsx_runtime_1.jsx)("div", Object.assign({ css: { ...style.firstRowMessageCss }, "data-gridrow": true }, { children: firstRowMessage }), void 0)), filteredRows.map(([, node]) => node)] }), void 0));
+        }, "data-testid": id }, { children: [totalsRows.map(([, node]) => node), headerRows.map(([, node]) => node), firstRowMessage && ((0, jsx_runtime_1.jsx)("div", Object.assign({ css: { ...style.firstRowMessageCss }, "data-gridrow": true }, { children: firstRowMessage }), void 0)), visibleDataRows.map(([, node]) => node)] }), void 0));
 }
 /** Renders as a table, primarily/solely for good print support. */
-function renderTable(style, id, columns, headerRows, totalsRows, filteredRows, firstRowMessage, _stickyHeader, _firstLastColumnWidth, xss, _virtuosoRef) {
+function renderTable(style, id, columns, headerRows, totalsRows, visibleDataRows, firstRowMessage, _stickyHeader, _firstLastColumnWidth, xss, _virtuosoRef) {
     return ((0, jsx_runtime_1.jsxs)("table", Object.assign({ css: {
             ...Css_1.Css.w100.add("borderCollapse", "collapse").$,
             ...Css_1.Css.addIn("& > tbody > tr ", style.betweenRowsCss || {})
@@ -302,7 +307,7 @@ function renderTable(style, id, columns, headerRows, totalsRows, filteredRows, f
             ...style.rootCss,
             ...(style.minWidthPx ? Css_1.Css.mwPx(style.minWidthPx).$ : {}),
             ...xss,
-        }, "data-testid": id }, { children: [(0, jsx_runtime_1.jsx)("thead", { children: [...totalsRows, ...headerRows].map(([, node]) => node) }, void 0), (0, jsx_runtime_1.jsxs)("tbody", { children: [firstRowMessage && ((0, jsx_runtime_1.jsx)("tr", { children: (0, jsx_runtime_1.jsx)("td", Object.assign({ colSpan: columns.length, css: { ...style.firstRowMessageCss } }, { children: firstRowMessage }), void 0) }, void 0)), filteredRows.map(([, node]) => node)] }, void 0)] }), void 0));
+        }, "data-testid": id }, { children: [(0, jsx_runtime_1.jsx)("thead", { children: [...totalsRows, ...headerRows].map(([, node]) => node) }, void 0), (0, jsx_runtime_1.jsxs)("tbody", { children: [firstRowMessage && ((0, jsx_runtime_1.jsx)("tr", { children: (0, jsx_runtime_1.jsx)("td", Object.assign({ colSpan: columns.length, css: { ...style.firstRowMessageCss } }, { children: firstRowMessage }), void 0) }, void 0)), visibleDataRows.map(([, node]) => node)] }, void 0)] }), void 0));
 }
 /**
  * Uses react-virtuoso to render rows virtually.
@@ -324,7 +329,7 @@ function renderTable(style, id, columns, headerRows, totalsRows, filteredRows, f
  * [2]: https://github.com/tannerlinsley/react-virtual/issues/85
  * [3]: https://github.com/tannerlinsley/react-virtual/issues/108
  */
-function renderVirtual(style, id, columns, headerRows, totalsRows, filteredRows, firstRowMessage, stickyHeader, firstLastColumnWidth, xss, virtuosoRef) {
+function renderVirtual(style, id, columns, headerRows, totalsRows, visibleDataRows, firstRowMessage, stickyHeader, firstLastColumnWidth, xss, virtuosoRef) {
     // eslint-disable-next-line react-hooks/rules-of-hooks
     const { footerStyle, listStyle } = (0, react_1.useMemo)(() => {
         var _a;
@@ -363,8 +368,8 @@ function renderVirtual(style, id, columns, headerRows, totalsRows, filteredRows,
                 index--;
             }
             // Lastly render `filteredRow`
-            return filteredRows[index][1];
-        }, totalCount: (headerRows.length || 0) + (totalsRows.length || 0) + (firstRowMessage ? 1 : 0) + (filteredRows.length || 0) }, void 0));
+            return visibleDataRows[index][1];
+        }, totalCount: (headerRows.length || 0) + (totalsRows.length || 0) + (firstRowMessage ? 1 : 0) + (visibleDataRows.length || 0) }, void 0));
 }
 /**
  * A table might render two of these components to represent two virtual lists.

package/dist/components/Table/RowState.d.ts

@@ -20,7 +20,7 @@ export declare class RowState {
     private readonly collapsedRows;
     private persistCollapse;
     private readonly selectedRows;
-    private visibleRows;
+    private matchedRows;
     rows: GridDataRow<any>[];
     activeRowId: string | undefined;
     /**
@@ -29,14 +29,14 @@ export declare class RowState {
     constructor();
     loadCollapse(persistCollapse: string | undefined, rows: GridDataRow<any>[]): void;
     setRows(rows: GridDataRow<any>[]): void;
-    setVisibleRows(rowIds: string[]): void;
+    setMatchedRows(rowIds: string[]): void;
     get selectedIds(): string[];
     getSelected(id: string): SelectedState;
     selectRow(id: string, selected: boolean): void;
     get collapsedIds(): string[];
     isCollapsed(id: string): boolean;
     toggleCollapsed(id: string): void;
-    private getVisibleChildrenStates;
+    private getMatchedChildrenStates;
     private setNestedSelectedStates;
 }
 /** Provides a context for rows to access their table's `RowState`. */

package/dist/components/Table/RowState.js

@@ -30,8 +30,8 @@ class RowState {
         // A set of just row ids, i.e. not row.kind+row.id
         this.collapsedRows = new mobx_1.ObservableSet();
         this.selectedRows = new mobx_1.ObservableMap();
-        // Set of just row ids. Keeps track of which rows are visible. Used to filter out non-visible rows from `selectedIds`
-        this.visibleRows = new mobx_1.ObservableSet();
+        // Set of just row ids. Keeps track of which rows match the filter. Used to filter rows from `selectedIds`
+        this.matchedRows = new mobx_1.ObservableSet();
         // The current list of rows, basically a useRef.current. Not reactive.
         this.rows = [];
         // Keeps track of the 'active' row, formatted `${row.kind}_${row.id}`
@@ -42,11 +42,11 @@ class RowState {
         // We only shallow observe rows so that:
         // a) we don't deeply/needlessly proxy-ize a large Apollo fragment cache, but
         // b) if rows changes, we re-run computeds like getSelectedRows that may need to see the
-        // updated _contents_ of a given row, even if our other selected/visible row states don't change.
+        // updated _contents_ of a given row, even if our other selected/matched row states don't change.
         // (as any b/c rows is private, so the mapped type doesn't see it)
         { rows: mobx_1.observable.shallow });
-        // Whenever our `visibleRows` change (i.e. via filtering) then we need to re-derive header and parent rows' selected state.
-        (0, mobx_1.reaction)(() => [...this.visibleRows.values()].sort(), () => {
+        // Whenever our `matchedRows` change (i.e. via filtering) then we need to re-derive header and parent rows' selected state.
+        (0, mobx_1.reaction)(() => [...this.matchedRows.values()].sort(), () => {
             const map = new Map();
             map.set("header", deriveParentSelected(this.rows.flatMap((row) => this.setNestedSelectedStates(row, map))));
             // Merge the changes back into the selected rows state
@@ -95,20 +95,20 @@ class RowState {
         // Finally replace our existing list of rows
         this.rows = rows;
     }
-    setVisibleRows(rowIds) {
+    setMatchedRows(rowIds) {
         // ObservableSet doesn't seem to do a `diff` inside `replace` before firing
         // observers/reactions that watch it, which can lead to render loops with the
         // application page is observing `GridTableApi.getSelectedRows`, and merely
         // the act of rendering GridTable (w/o row changes) causes it's `useComputed`
         // to be triggered.
-        if (!mobx_1.comparer.shallow(rowIds, [...this.visibleRows.values()])) {
-            this.visibleRows.replace(rowIds);
+        if (!mobx_1.comparer.shallow(rowIds, [...this.matchedRows.values()])) {
+            this.matchedRows.replace(rowIds);
         }
     }
     get selectedIds() {
         // Return only ids that are fully checked, i.e. not partial
         const ids = [...this.selectedRows.entries()]
-            .filter(([id, v]) => this.visibleRows.has(id) && v === "checked")
+            .filter(([id, v]) => this.matchedRows.has(id) && v === "checked")
             .map(([k]) => k);
         // Hide our header marker
         const headerIndex = ids.indexOf("header");
@@ -129,7 +129,7 @@ class RowState {
                 // Just mash the header + all rows + children as selected
                 const map = new Map();
                 map.set("header", "checked");
-                (0, visitor_1.visit)(this.rows, (row) => this.visibleRows.has(row.id) && row.kind !== "totals" && map.set(row.id, "checked"));
+                (0, visitor_1.visit)(this.rows, (row) => this.matchedRows.has(row.id) && row.kind !== "totals" && map.set(row.id, "checked"));
                 this.selectedRows.replace(map);
             }
             else {
@@ -147,15 +147,15 @@ class RowState {
             }
             // Everything here & down is deterministically on/off
             const map = new Map();
-            (0, visitor_1.visit)([curr.row], (row) => this.visibleRows.has(row.id) && map.set(row.id, selected ? "checked" : "unchecked"));
+            (0, visitor_1.visit)([curr.row], (row) => this.matchedRows.has(row.id) && map.set(row.id, selected ? "checked" : "unchecked"));
             // Now walk up the parents and see if they are now-all-checked/now-all-unchecked/some-of-each
             for (const parent of [...curr.parents].reverse()) {
                 if (parent.children) {
-                    map.set(parent.id, deriveParentSelected(this.getVisibleChildrenStates(parent.children, map)));
+                    map.set(parent.id, deriveParentSelected(this.getMatchedChildrenStates(parent.children, map)));
                 }
             }
             // And do the header + top-level "children" as a final one-off
-            map.set("header", deriveParentSelected(this.getVisibleChildrenStates(this.rows, map)));
+            map.set("header", deriveParentSelected(this.getMatchedChildrenStates(this.rows, map)));
             this.selectedRows.merge(map);
         }
     }
@@ -218,14 +218,14 @@ class RowState {
             sessionStorage.setItem(this.persistCollapse, JSON.stringify(collapsedIds));
         }
     }
-    getVisibleChildrenStates(children, map) {
+    getMatchedChildrenStates(children, map) {
         return children
-            .filter((row) => row.id !== "header" && this.visibleRows.has(row.id))
+            .filter((row) => row.id !== "header" && this.matchedRows.has(row.id))
             .map((row) => map.get(row.id) || this.getSelected(row.id));
     }
     // Recursively traverse through rows to determine selected state of parent rows based on children
     setNestedSelectedStates(row, map) {
-        if (this.visibleRows.has(row.id)) {
+        if (this.matchedRows.has(row.id)) {
             if (!row.children) {
                 return [this.getSelected(row.id)];
             }

package/dist/inputs/MultiSelectField.d.ts

@@ -2,7 +2,7 @@ import { ReactNode } from "react";
 import { Value } from "./";
 import { BeamSelectFieldBaseProps } from "./internal/SelectFieldBase";
 import { HasIdAndName, Optional } from "../types";
-export interface MultiSelectFieldProps<O, V extends Value> extends BeamSelectFieldBaseProps<O, V> {
+export interface MultiSelectFieldProps<O, V extends Value> extends Exclude<BeamSelectFieldBaseProps<O, V>, "unsetLabel"> {
     /** Renders `opt` in the dropdown menu, defaults to the `getOptionLabel` prop. */
     getOptionMenuLabel?: (opt: O) => string | ReactNode;
     getOptionValue: (opt: O) => V;

package/dist/inputs/SelectField.d.ts

@@ -4,7 +4,7 @@ import { HasIdAndName, Optional } from "../types";
 export interface SelectFieldProps<O, V extends Value> extends Omit<BeamSelectFieldBaseProps<O, V>, "values" | "onSelect"> {
     /** The current value; it can be `undefined`, even if `V` cannot be. */
     value: V | undefined;
-    onSelect: (value: V, opt: O) => void;
+    onSelect: (value: V | undefined, opt: O | undefined) => void;
 }
 /**
  * Provides a non-native select/dropdown widget.

package/dist/inputs/SelectField.js

@@ -9,7 +9,8 @@ function SelectField(props) {
     options, onSelect, value, ...otherProps } = props;
     return ((0, jsx_runtime_1.jsx)(SelectFieldBase_1.SelectFieldBase, Object.assign({}, otherProps, { options: options, getOptionLabel: getOptionLabel, getOptionValue: getOptionValue, values: [value], onSelect: (values, options) => {
             if (values.length > 0 && options.length > 0) {
-                onSelect && onSelect(values[0], options[0]);
+                const option = options[0];
+                onSelect(values[0], option === SelectFieldBase_1.unsetOption ? undefined : option);
             }
         } }), void 0));
 }

package/dist/inputs/internal/SelectFieldBase.d.ts

@@ -3,8 +3,8 @@ import { PresentationFieldProps } from "../../components/PresentationContext";
 import { Value } from "../Value";
 import { BeamFocusableProps } from "../../interfaces";
 export interface BeamSelectFieldBaseProps<O, V extends Value> extends BeamFocusableProps, PresentationFieldProps {
-    /** Renders `opt` in the dropdown menu, defaults to the `getOptionLabel` prop. */
-    getOptionMenuLabel?: (opt: O) => string | ReactNode;
+    /** Renders `opt` in the dropdown menu, defaults to the `getOptionLabel` prop. `isUnsetOpt` is only defined for single SelectField */
+    getOptionMenuLabel?: (opt: O, isUnsetOpt?: boolean) => string | ReactNode;
     getOptionValue: (opt: O) => V;
     getOptionLabel: (opt: O) => string;
     /** The current value; it can be `undefined`, even if `V` cannot be. */
@@ -12,12 +12,7 @@ export interface BeamSelectFieldBaseProps<O, V extends Value> extends BeamFocusa
     onSelect: (values: V[], opts: O[]) => void;
     multiselect?: boolean;
     disabledOptions?: V[];
-    options: O[] | {
-        initial: O[];
-        load: () => Promise<{
-            options: O[];
-        }>;
-    };
+    options: OptionsOrLoad<O>;
     /** Whether the field is disabled. If a ReactNode, it's treated as a "disabled reason" that's shown in a tooltip. */
     disabled?: boolean | ReactNode;
     required?: boolean;
@@ -39,6 +34,8 @@ export interface BeamSelectFieldBaseProps<O, V extends Value> extends BeamFocusa
     contrast?: boolean;
     /** Placeholder content */
     placeholder?: string;
+    /** Only used for Single Select Fields. If set, prepends an option with a `undefined` value at the top of the list */
+    unsetLabel?: string;
 }
 /**
  * Provides a non-native select/dropdown widget.
@@ -50,3 +47,12 @@ export interface BeamSelectFieldBaseProps<O, V extends Value> extends BeamFocusa
  * and so we cannot easily change them.
  */
 export declare function SelectFieldBase<O, V extends Value>(props: BeamSelectFieldBaseProps<O, V>): JSX.Element;
+declare type OptionsOrLoad<O> = O[] | {
+    initial: O[];
+    load: () => Promise<{
+        options: O[];
+    }>;
+};
+export declare function initializeOptions<O>(options: OptionsOrLoad<O>, unsetLabel: string | undefined): OptionsOrLoad<O>;
+export declare const unsetOption: {};
+export {};

package/dist/inputs/internal/SelectFieldBase.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SelectFieldBase = void 0;
+exports.unsetOption = exports.initializeOptions = exports.SelectFieldBase = void 0;
 const jsx_runtime_1 = require("@emotion/react/jsx-runtime");
 const react_1 = require("react");
 const react_aria_1 = require("react-aria");
@@ -23,7 +23,15 @@ const utils_1 = require("../../utils");
  */
 function SelectFieldBase(props) {
     var _a;
-    const { disabled, readOnly, onSelect, options: maybeOptions, multiselect = false, getOptionLabel, getOptionValue, getOptionMenuLabel = getOptionLabel, values = [], nothingSelectedText = "", contrast, disabledOptions, borderless, ...otherProps } = props;
+    const { disabled, readOnly, onSelect, options, multiselect = false, values = [], nothingSelectedText = "", contrast, disabledOptions, borderless, unsetLabel, ...otherProps } = props;
+    // Call `initializeOptions` to prepend the `unset` option if the `unsetLabel` was provided.
+    const maybeOptions = (0, react_1.useMemo)(() => initializeOptions(options, unsetLabel), [options, unsetLabel]);
+    // Memoize the callback functions and handle the `unset` option if provided.
+    const getOptionLabel = (0, react_1.useCallback)((o) => (unsetLabel && o === exports.unsetOption ? unsetLabel : props.getOptionLabel(o)), [props.getOptionLabel, unsetLabel]);
+    const getOptionValue = (0, react_1.useCallback)((o) => (unsetLabel && o === exports.unsetOption ? undefined : props.getOptionValue(o)), [props.getOptionValue, unsetLabel]);
+    const getOptionMenuLabel = (0, react_1.useCallback)((o) => props.getOptionMenuLabel
+        ? props.getOptionMenuLabel(o, Boolean(unsetLabel) && o === exports.unsetOption)
+        : getOptionLabel(o), [props.getOptionValue, unsetLabel, getOptionLabel]);
     const { contains } = (0, react_aria_1.useFilter)({ sensitivity: "base" });
     const isDisabled = !!disabled;
     const isReadOnly = !!readOnly;
@@ -105,7 +113,9 @@ function SelectFieldBase(props) {
     async function maybeInitLoad() {
         if (!Array.isArray(maybeOptions)) {
             setFieldState((prevState) => ({ ...prevState, optionsLoading: true }));
-            const { options } = await maybeOptions.load();
+            const loadedOptions = (await maybeOptions.load()).options;
+            // Ensure the `unset` option is prepended to the top of the list if `unsetLabel` was provided
+            const options = !unsetLabel ? loadedOptions : getOptionsWithUnset(unsetLabel, loadedOptions);
             setFieldState((prevState) => ({
                 ...prevState,
                 filteredOptions: options,
@@ -245,3 +255,17 @@ function getInputValue(selectedOptions, getOptionLabel, multiselect, nothingSele
             ? nothingSelectedText
             : "";
 }
+function initializeOptions(options, unsetLabel) {
+    if (!unsetLabel) {
+        return options;
+    }
+    if (Array.isArray(options)) {
+        return getOptionsWithUnset(unsetLabel, options);
+    }
+    return { ...options, initial: getOptionsWithUnset(unsetLabel, options.initial) };
+}
+exports.initializeOptions = initializeOptions;
+function getOptionsWithUnset(unsetLabel, options) {
+    return [exports.unsetOption, ...options];
+}
+exports.unsetOption = {};

package/dist/types.d.ts

@@ -9,3 +9,4 @@ export declare type CanCloseCheck = {
     discardText?: string;
     continueText?: string;
 } | CheckFn;
+export declare function assertNever(x: never): never;

package/dist/types.js

@@ -1,2 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertNever = void 0;
+function assertNever(x) {
+    throw new Error("Unexpected object: " + x);
+}
+exports.assertNever = assertNever;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homebound/beam",
-  "version": "2.135.2",
+  "version": "2.137.0",
   "author": "Homebound",
   "license": "MIT",
   "main": "dist/index.js",
@@ -32,7 +32,7 @@
     "format": "prettier --loglevel warn --write \"**/*.{ts,tsx,css,md}\""
   },
   "dependencies": {
-    "@homebound/form-state": "2.14.0",
+    "@homebound/form-state": "2.15.1",
     "@internationalized/number": "^3.0.3",
     "@react-aria/utils": "^3.11.3",
     "@react-hook/resize-observer": "^1.2.2",