@homebound/beam 2.363.0 → 2.365.0

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

@@ -131,6 +131,13 @@ export interface GridTableProps<R extends Kinded, X> {
     infiniteScroll?: InfiniteScroll;
     /** Callback for when a row is selected or unselected. */
     onRowSelect?: OnRowSelect<R>;
+    /**
+     * Custom prefix rows for any CSV output, i.e. a header like "Report X as of date Y with filter Z".
+     *
+     * We except the `string[][]` to be an array of cells, and `copyToClipboard` and `downloadToCsv` will drop them into
+     * the csv output basically unchanged, albeit we will escape any special chars like double quotes and newlines.
+     */
+    csvPrefixRows?: string[][];
     /** Drag & drop Callback. */
     onRowDrop?: (draggedRow: GridDataRow<R>, droppedRow: GridDataRow<R>, indexOffset: number) => void;
 }

package/dist/components/Table/GridTable.js

@@ -88,7 +88,7 @@ exports.setGridTableDefaults = setGridTableDefaults;
  */
 function GridTable(props) {
     var _a, _b, _c;
-    const { id = "gridTable", as = "div", columns: _columns, rows, style: maybeStyle = defaults.style, rowStyles, stickyHeader = defaults.stickyHeader, stickyOffset = 0, xss, filter, filterMaxRows, fallbackMessage = "No rows found.", infoMessage, persistCollapse, resizeTarget, activeRowId, activeCellId, visibleColumnsStorageKey, infiniteScroll, onRowSelect, onRowDrop: droppedCallback, } = props;
+    const { id = "gridTable", as = "div", columns: _columns, rows, style: maybeStyle = defaults.style, rowStyles, stickyHeader = defaults.stickyHeader, stickyOffset = 0, xss, filter, filterMaxRows, fallbackMessage = "No rows found.", infoMessage, persistCollapse, resizeTarget, activeRowId, activeCellId, visibleColumnsStorageKey, infiniteScroll, onRowSelect, onRowDrop: droppedCallback, csvPrefixRows, } = props;
     const columnsWithIds = (0, react_1.useMemo)(() => (0, columns_1.assignDefaultColumnIds)(_columns), [_columns]);
     // We only use this in as=virtual mode, but keep this here for rowLookup to use
     const virtuosoRef = (0, react_1.useRef)(null);
@@ -129,10 +129,11 @@ function GridTable(props) {
             tableState.setRows(rows);
             tableState.setColumns(columnsWithIds, visibleColumnsStorageKey);
             tableState.setSearch(filter);
+            tableState.setCsvPrefixRows(csvPrefixRows);
             tableState.activeRowId = activeRowId;
             tableState.activeCellId = activeCellId;
         });
-    }, [tableState, rows, columnsWithIds, visibleColumnsStorageKey, activeRowId, activeCellId, filter]);
+    }, [tableState, rows, columnsWithIds, visibleColumnsStorageKey, activeRowId, activeCellId, filter, csvPrefixRows]);
     const columns = (0, hooks_1.useComputed)(() => {
         return tableState.visibleColumns;
     }, [tableState]);

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

@@ -1,6 +1,6 @@
 import { MutableRefObject } from "react";
 import { VirtuosoHandle } from "react-virtuoso";
-import { GridRowLookup } from "../index";
+import { GridRowLookup, MaybeFn } from "../index";
 import { GridDataRow } from "./components/Row";
 import { DiscriminateUnion, Kinded } from "./types";
 import { TableState } from "./utils/TableState";
@@ -51,6 +51,18 @@ export type GridTableApi<R extends Kinded> = {
     deleteRows(ids: string[]): void;
     getVisibleColumnIds(): string[];
     setVisibleColumns(ids: string[]): void;
+    /**
+     * Triggers the table's current content to be downloaded as a CSV file.
+     *
+     * This currently assumes client-side pagination/sorting, i.e. we have the full dataset in memory.
+     */
+    downloadToCsv(fileName: string): void;
+    /**
+     * Copies the table's current content to the clipboard.
+     *
+     * This currently assumes client-side pagination/sorting, i.e. we have the full dataset in memory.
+     */
+    copyToClipboard(): Promise<void>;
 };
 /** Adds per-row methods to the `api`, i.e. for getting currently-visible children. */
 export type GridRowApi<R extends Kinded> = GridTableApi<R> & {
@@ -84,4 +96,8 @@ export declare class GridTableApiImpl<R extends Kinded> implements GridTableApi<
     setVisibleColumns(ids: string[]): void;
     getVisibleColumnIds(): string[];
     deleteRows(ids: string[]): void;
+    downloadToCsv(fileName: string): void;
+    copyToClipboard(): Promise<void>;
+    generateCsvContent(): string[];
 }
+export declare function maybeApply<T>(maybeFn: MaybeFn<T>): T;

package/dist/components/Table/GridTableApi.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GridTableApiImpl = exports.useGridTableApi = void 0;
+exports.maybeApply = exports.GridTableApiImpl = exports.useGridTableApi = void 0;
 const mobx_1 = require("mobx");
 const mobx_utils_1 = require("mobx-utils");
 const react_1 = require("react");
@@ -107,11 +107,87 @@ class GridTableApiImpl {
     deleteRows(ids) {
         this.tableState.deleteRows(ids);
     }
+    downloadToCsv(fileName) {
+        // Create a link element, set the download attribute with the provided filename
+        const link = document.createElement("a");
+        if (link.download === undefined)
+            throw new Error("This browser does not support the download attribute.");
+        // Create a Blob from the CSV content
+        const url = URL.createObjectURL(new Blob([this.generateCsvContent().join("\n")], { type: "text/csv;charset=utf-8;" }));
+        link.setAttribute("href", url);
+        link.setAttribute("download", fileName);
+        link.style.visibility = "hidden";
+        document.body.appendChild(link);
+        link.click();
+        document.body.removeChild(link);
+    }
+    copyToClipboard() {
+        // Copy the CSV content to the clipboard
+        const content = this.generateCsvContent().join("\n");
+        return navigator.clipboard.writeText(content).catch((err) => {
+            // Let the user know the copy failed...
+            window.alert("Failed to copy to clipboard, probably due to browser restrictions.");
+            throw err;
+        });
+    }
+    // visibleForTesting, not part of the GridTableApi
+    // ...although maybe it could be public someday, to allow getting the raw the CSV content
+    // and then sending it somewhere else, like directly to a gsheet.
+    generateCsvContent() {
+        var _a, _b;
+        const csvPrefixRows = (_b = (_a = this.tableState.csvPrefixRows) === null || _a === void 0 ? void 0 : _a.map((row) => row.map(escapeCsvValue).join(","))) !== null && _b !== void 0 ? _b : [];
+        // Convert the array of rows into CSV format
+        const dataRows = this.tableState.visibleRows.map((rs) => {
+            const values = this.tableState.visibleColumns
+                .filter((c) => !c.isAction)
+                .map((c) => {
+                // Just guessing for level=1
+                const maybeContent = (0, index_1.applyRowFn)(c, rs.row, this, 1, true, undefined);
+                if ((0, index_1.isGridCellContent)(maybeContent)) {
+                    const cell = maybeContent;
+                    const content = maybeApply(cell.content);
+                    // Anything not isJSX (like a string) we can put into the CSV directly
+                    if (!(0, index_1.isJSX)(content))
+                        return content;
+                    // Otherwise use the value/sortValue values
+                    return cell.value ? maybeApply(cell.value) : cell.sortValue ? maybeApply(cell.sortValue) : "-";
+                }
+                else {
+                    // ReactNode
+                    return (0, index_1.isJSX)(maybeContent) ? "-" : maybeContent;
+                }
+            });
+            return values.map(toCsvString).map(escapeCsvValue).join(",");
+        });
+        return [...csvPrefixRows, ...dataRows];
+    }
 }
 exports.GridTableApiImpl = GridTableApiImpl;
+function toCsvString(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return value.toString();
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    return String(value);
+}
+function escapeCsvValue(value) {
+    // Wrap values with special chars in quotes, and double quotes themselves
+    if (value.includes('"') || value.includes(",") || value.includes("\n")) {
+        return `"${value.replace(/"/g, '""')}"`;
+    }
+    return value;
+}
 function bindMethods(instance) {
     Object.getOwnPropertyNames(Object.getPrototypeOf(instance)).forEach((key) => {
         if (instance[key] instanceof Function && key !== "constructor")
             instance[key] = instance[key].bind(instance);
     });
 }
+function maybeApply(maybeFn) {
+    return typeof maybeFn === "function" ? maybeFn() : maybeFn;
+}
+exports.maybeApply = maybeApply;

package/dist/components/Table/components/Row.js

@@ -119,14 +119,16 @@ function RowImpl(props) {
                 currentColspan -= 1;
                 return null;
             }
-            const maybeContent = (0, utils_1.applyRowFn)(column, row, rowApi, level, isExpanded, {
+            // Combine all our drag stuff into a mini-context/parameter object...
+            const dragData = {
                 rowRenderRef: ref,
                 onDragStart,
                 onDragEnd,
                 onDrop,
                 onDragEnter,
                 onDragOver: onDragOverDebounced,
-            });
+            };
+            const maybeContent = (0, utils_1.applyRowFn)(column, row, rowApi, level, isExpanded, dragData);
             // Only use the `numExpandedColumns` as the `colspan` when rendering the "Expandable Header"
             currentColspan =
                 (0, utils_1.isGridCellContent)(maybeContent) && typeof maybeContent.colspan === "number"

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

@@ -6,10 +6,14 @@ import { Properties, Typography } from "../../../Css";
 /**
  * Allows a cell to be more than just a RectNode, i.e. declare its alignment or
  * primitive value for filtering and sorting.
+ *
+ * For a given column, the `GridColumn` can either return a static `GridCellContent`, or
+ * more likely use a function that returns a per-column/per-row `GridCellContent` that defines
+ * the value (and it's misc alignment/css/etc) for this specific cell.
  */
 export type GridCellContent = {
     /** The JSX content of the cell. Virtual tables that client-side sort should use a function to avoid perf overhead. */
-    content: ReactNode | (() => ReactNode);
+    content: MaybeFn<ReactNode>;
     alignment?: GridCellAlignment;
     /** Allow value to be a function in case it's a dynamic value i.e. reading from an inline-edited proxy. */
     value?: MaybeFn<number | string | Date | boolean | null | undefined>;

package/dist/components/Table/utils/TableState.d.ts

@@ -32,6 +32,8 @@ export declare class TableState<R extends Kinded> {
     activeCellId: string | undefined;
     /** Stores the current client-side type-ahead search/filter. */
     search: string[];
+    /** Stores whether CSVs should have some prefix rows. */
+    csvPrefixRows: string[][] | undefined;
     sortConfig: GridSortConfig | undefined;
     sort: SortState;
     private initialSortState;
@@ -50,6 +52,7 @@ export declare class TableState<R extends Kinded> {
     setRows(rows: GridDataRow<R>[]): void;
     setColumns(columns: GridColumnWithId<R>[], visibleColumnsStorageKey: string | undefined): void;
     setSearch(search: string | undefined): void;
+    setCsvPrefixRows(csvPrefixRows: string[][] | undefined): void;
     get visibleRows(): RowState<R>[];
     /** Returns visible columns, i.e. those that are visible + any expanded children. */
     get visibleColumns(): GridColumnWithId<R>[];

package/dist/components/Table/utils/TableState.js

@@ -42,6 +42,8 @@ class TableState {
         this.activeCellId = undefined;
         /** Stores the current client-side type-ahead search/filter. */
         this.search = [];
+        /** Stores whether CSVs should have some prefix rows. */
+        this.csvPrefixRows = undefined;
         // Tracks the active sort column(s), so GridTable or SortHeaders can reactively
         // re-render (for GridTable, only if client-side sorting)
         this.sort = {};
@@ -143,6 +145,9 @@ class TableState {
         // Break up "foo bar" into `[foo, bar]` and a row must match both `foo` and `bar`
         this.search = (search && search.split(/ +/)) || [];
     }
+    setCsvPrefixRows(csvPrefixRows) {
+        this.csvPrefixRows = csvPrefixRows;
+    }
     get visibleRows() {
         return this.rowStates.visibleRows;
     }

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

@@ -22,6 +22,8 @@ export declare const ASC: "ASC";
 export declare const DESC: "DESC";
 export declare const emptyCell: GridCellContent;
 export declare function getFirstOrLastCellCss<R extends Kinded>(style: GridStyle, columnIndex: number, columns: GridColumnWithId<R>[]): Properties;
+/** A heuristic to detect the result of `React.createElement` / i.e. JSX. */
+export declare function isJSX(content: any): boolean;
 export declare function getAlignment(column: GridColumnWithId<any>, maybeContent: ReactNode | GridCellContent): GridCellAlignment;
 export declare function getJustification(column: GridColumnWithId<any>, maybeContent: ReactNode | GridCellContent, as: RenderAs, alignment: GridCellAlignment): {
     textAlign: import("csstype").Property.TextAlign | undefined;

package/dist/components/Table/utils/utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTableRefWidthStyles = exports.recursivelyGetContainingRow = exports.isCursorBelowMidpoint = exports.insertAtIndex = exports.loadArrayOrUndefined = exports.zIndices = exports.reservedRowKinds = exports.KEPT_GROUP = exports.EXPANDABLE_HEADER = exports.TOTALS = exports.HEADER = exports.matchesFilter = exports.maybeApplyFunction = exports.getJustification = exports.getAlignment = exports.getFirstOrLastCellCss = exports.emptyCell = exports.DESC = exports.ASC = exports.applyRowFn = exports.isGridCellContent = exports.toContent = void 0;
+exports.getTableRefWidthStyles = exports.recursivelyGetContainingRow = exports.isCursorBelowMidpoint = exports.insertAtIndex = exports.loadArrayOrUndefined = exports.zIndices = exports.reservedRowKinds = exports.KEPT_GROUP = exports.EXPANDABLE_HEADER = exports.TOTALS = exports.HEADER = exports.matchesFilter = exports.maybeApplyFunction = exports.getJustification = exports.getAlignment = exports.isJSX = exports.getFirstOrLastCellCss = exports.emptyCell = exports.DESC = exports.ASC = exports.applyRowFn = exports.isGridCellContent = exports.toContent = void 0;
 const jsx_runtime_1 = require("@emotion/react/jsx-runtime");
 const Icon_1 = require("../../Icon");
 const ExpandableHeader_1 = require("../components/ExpandableHeader");
@@ -98,6 +98,7 @@ exports.getFirstOrLastCellCss = getFirstOrLastCellCss;
 function isJSX(content) {
     return typeof content === "object" && content && "type" in content && "props" in content;
 }
+exports.isJSX = isJSX;
 const alignmentToJustify = {
     left: "flex-start",
     center: "center",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homebound/beam",
-  "version": "2.363.0",
+  "version": "2.365.0",
   "author": "Homebound",
   "license": "MIT",
   "main": "dist/index.js",