@linzjs/step-ag-grid 1.1.1

package/package.json

@@ -0,0 +1,126 @@
+{
+  "name": "@linzjs/step-ag-grid",
+  "repository": "github:linz/step-ag-grid.git",
+  "license": "MIT",
+  "version": "1.1.1",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "module": "dist/step-ag-grid.esm.js",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=10"
+  },
+  "resolutions": {
+    "webpack": "5"
+  },
+  "dependencies": {
+    "@linzjs/lui": "^17.18.2",
+    "@testing-library/jest-dom": "^5.14.1",
+    "@testing-library/react": "^12.1.3",
+    "@testing-library/user-event": "^13.5.0",
+    "ag-grid-community": "^27.3.0",
+    "ag-grid-react": "^27.3.0",
+    "debounce-promise": "^3.1.2",
+    "lodash-es": "^4.17.21",
+    "react": "^17.0.2",
+    "react-dom": "^17.0.2",
+    "react-scripts": "^5.0.1",
+    "uuid": "^9.0.0",
+    "autoprefixer": "^10.0.2",
+    "postcss": "^8.1.7",
+    "postcss-loader": "^4.0.4"
+  },
+  "scripts": {
+    "build": "rollup -c && npm run",
+    "test": "react-app-rewired test --passWithNoTests",
+    "eject": "react-app-rewired eject",
+    "lint": "eslint ./src --ext .js,.ts,.tsx --fix --cache",
+    "storybook": "start-storybook -p 6006 -s public",
+    "build-storybook": "build-storybook -s public",
+    "deploy-storybook": "npx --yes -p @storybook/storybook-deployer storybook-to-ghpages",
+    "chromatic": "chromatic --exit-zero-on-changes",
+    "semantic-release": "semantic-release"
+  },
+  "eslintConfig": {
+    "extends": [
+      "react-app",
+      "react-app/jest"
+    ]
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^21.0.2",
+    "@rollup/plugin-json": "^4.1.0",
+    "@rollup/plugin-node-resolve": "^11.2.1",
+    "@semantic-release/changelog": "^6.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@storybook/builder-webpack5": "^6.5.13",
+    "@storybook/cli": "^6.5.12",
+    "@storybook/manager-webpack5": "^6.5.13",
+    "@storybook/preset-scss": "^1.0.3",
+    "@storybook/react": "^6.5.12",
+    "@types/debounce-promise": "^3.1.4",
+    "@types/jest": "^27.5.2",
+    "@types/lodash-es": "^4.17.6",
+    "@types/node": "^16.18.0",
+    "@types/react": "^17.0.50",
+    "@types/react-dom": "^17.0.17",
+    "@types/uuid": "^8.3.4",
+    "@typescript-eslint/parser": "^5.39.0",
+    "babel-preset-react-app": "10.0.0",
+    "chromatic": "^6.10.1",
+    "css-loader": "^5.2.7",
+    "eslint": "8.22.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-config-react-app": "^7.0.1",
+    "eslint-plugin-deprecation": "^1.3.2",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-jest": "^26.1.5",
+    "eslint-plugin-jsx-a11y": "^6.5.1",
+    "eslint-plugin-prettier": "^4.0.0",
+    "eslint-plugin-react": "^7.29.4",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-testing-library": "^5.3.1",
+    "prettier": "^2.2.1",
+    "react-app-rewired": "^2.2.1",
+    "rollup": "^2.56.3",
+    "rollup-plugin-copy": "^3.4.0",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-postcss": "^4.0.2",
+    "rollup-plugin-typescript2": "^0.31.2",
+    "sass": "^1.49.9",
+    "sass-loader": "^10.3.1",
+    "semantic-release": "^19.0.5",
+    "style-loader": "^2.0.0",
+    "tsconfig-paths-webpack-plugin": "^4.0.0",
+    "typescript": "^4.8.4",
+    "webpack": "^5.74.0"
+  },
+  "babel": {
+    "presets": [
+      "react-app"
+    ]
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "npm run lint"
+    }
+  }
+}

package/src/components/ComponentLoadingWrapper.tsx

@@ -0,0 +1,31 @@
+import { LuiMiniSpinner } from "@linzjs/lui";
+
+/**
+ * If loading is true this returns a loading spinner, otherwise it returns its children.
+ */
+export const ComponentLoadingWrapper = (props: {
+  loading?: boolean;
+  saving?: boolean;
+  children: JSX.Element | undefined;
+}): JSX.Element => {
+  return props.loading ? (
+    <LuiMiniSpinner size={22} divProps={{ role: "status", ["aria-label"]: "Loading", style: { padding: 16 } }} />
+  ) : (
+    <div style={{ maxHeight: 400, overflowY: "auto", pointerEvents: props.saving ? "none" : "inherit" }}>
+      {props.saving && (
+        <div
+          style={{
+            position: "absolute",
+            left: 0,
+            top: 0,
+            bottom: 0,
+            right: 0,
+            backgroundColor: "rgba(64,64,64,0.1)",
+            zIndex: 1000,
+          }}
+        />
+      )}
+      {props.children}
+    </div>
+  );
+};

package/src/components/GenericCellClass.tsx

@@ -0,0 +1,15 @@
+import { CellClassFunc } from "ag-grid-community";
+
+export const GenericMultiEditCellClass: CellClassFunc = (props): string => {
+  const api = props.api;
+  if (api == null) return "";
+
+  const rowSelected = api
+    .getSelectedNodes()
+    .map((row) => row.id)
+    .includes(props.node.id);
+
+  return rowSelected && api.getEditingCells().some((cell) => cell.column.getColDef() === props.colDef)
+    ? "ag-selected-for-edit"
+    : "";
+};

package/src/components/Grid.scss

@@ -0,0 +1,38 @@
+@use '~@linzjs/lui/dist/scss/Core' as lui;
+
+.Grid-container {
+  flex: 1;
+  width: 100%;
+}
+
+.Grid-sortIsStale {
+  span.ag-icon.ag-icon-desc:after {
+    content: "*";
+  }
+
+  span.ag-icon.ag-icon-asc:after {
+    content: "*";
+  }
+}
+
+.Grid-quickFilter {
+  width: 100%;
+  margin-bottom: 16px;
+}
+
+.Grid-quickFilterBox {
+  width: 100%;
+  height: 48px;
+  border: 0.06rem solid lui.$silver;
+  border-radius: 3px;
+  padding-left: 0.75rem;
+  padding-right: 0.75rem;
+}
+
+.Grid-popoverContainer {
+  padding: 4px 8px;
+}
+
+.Grid-popoverContainerList {
+  padding: 4px 4px;
+}

package/src/components/Grid.tsx

@@ -0,0 +1,262 @@
+import "./Grid.scss";
+import "./GridTheme.scss";
+
+import clsx from "clsx";
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { AgGridReact } from "ag-grid-react";
+import { AgGridEvent, CellClickedEvent, ColDef } from "ag-grid-community";
+import { CellEvent, GridReadyEvent, SelectionChangedEvent } from "ag-grid-community/dist/lib/events";
+import { GridOptions } from "ag-grid-community/dist/lib/entities/gridOptions";
+import { difference, last, xorBy } from "lodash-es";
+import { GridContext } from "../contexts/GridContext";
+import { usePostSortRowsHook } from "./PostSortRowsHook";
+import { isNotEmpty } from "../utils/util";
+import { GridHeaderSelect } from "./gridHeader/GridHeaderSelect";
+import { UpdatingContext } from "../contexts/UpdatingContext";
+
+export interface GridBaseRow {
+  id: string | number;
+}
+
+export interface GridProps {
+  dataTestId?: string;
+  quickFilter?: boolean;
+  quickFilterPlaceholder?: string;
+  quickFilterValue?: string;
+  externalSelectedItems: any[];
+  setExternalSelectedItems: (items: any[]) => void;
+  onGridReady?: GridOptions["onGridReady"];
+  defaultColDef: GridOptions["defaultColDef"];
+  columnDefs: GridOptions["columnDefs"];
+  rowData: GridOptions["rowData"];
+  noRowsOverlayText?: string;
+}
+
+/**
+ * Wrapper for AgGrid to add commonly used functionality.
+ */
+export const Grid = (params: GridProps): JSX.Element => {
+  const { gridReady, setGridApi, setQuickFilter, ensureRowVisible, selectRowsById, ensureSelectedRowIsVisible } =
+    useContext(GridContext);
+  const { checkUpdating } = useContext(UpdatingContext);
+
+  const [internalQuickFilter, setInternalQuickFilter] = useState("");
+  const lastSelectedIds = useRef<number[]>([]);
+  const [staleGrid, setStaleGrid] = useState(false);
+  const postSortRows = usePostSortRowsHook({ setStaleGrid });
+
+  /**
+   * AgGrid checkbox select does not pass clicks within cell but not on the checkbox to checkbox.
+   * This passes the event to the checkbox when you click anywhere in the cell.
+   */
+  const clickSelectorCheckboxWhenContainingCellClicked = useCallback(({ event }: CellClickedEvent) => {
+    if (!event) return;
+    const input = (event.target as Element).querySelector("input");
+    input?.dispatchEvent(event);
+  }, []);
+
+  /**
+   * Ensure external selected items list is in sync with panel.
+   */
+  const synchroniseExternalStateToGridSelection = ({ api }: SelectionChangedEvent) => {
+    const selectedRows = api.getSelectedRows();
+    // We don't want to update selected Items if it hasn't changed to prevent excess renders
+    if (
+      params.externalSelectedItems.length != selectedRows.length ||
+      isNotEmpty(xorBy(selectedRows, params.externalSelectedItems, (row) => row.id))
+    ) {
+      params.setExternalSelectedItems([...selectedRows]);
+    }
+  };
+
+  /**
+   * Synchronise externally selected items to grid.
+   * If new ids are selected scroll them into view.
+   */
+  const synchroniseExternallySelectedItemsToGrid = useCallback(() => {
+    if (!gridReady()) return;
+
+    const selectedIds = params.externalSelectedItems.map((row) => row.id) as number[];
+    const lastNewId = last(difference(selectedIds, lastSelectedIds.current));
+    if (lastNewId != null) ensureRowVisible(lastNewId);
+    lastSelectedIds.current = selectedIds;
+    selectRowsById(selectedIds);
+  }, [params.externalSelectedItems, ensureRowVisible, gridReady, selectRowsById]);
+
+  /**
+   * Synchronise quick filter to grid
+   */
+  const updateQuickFilter = useCallback(() => {
+    if (!gridReady()) return;
+    if (params.quickFilter) {
+      setQuickFilter(internalQuickFilter);
+      return;
+    }
+    if (params.quickFilterValue == null) return;
+    setQuickFilter(params.quickFilterValue);
+  }, [gridReady, internalQuickFilter, params.quickFilter, params.quickFilterValue, setQuickFilter]);
+
+  /**
+   * Synchronise quick filter to grid
+   */
+  useEffect(() => {
+    updateQuickFilter();
+  }, [updateQuickFilter]);
+
+  /**
+   * Synchronise externally selected items to grid on externalSelectedItems change
+   */
+  useEffect(() => {
+    synchroniseExternallySelectedItemsToGrid();
+  }, [synchroniseExternallySelectedItemsToGrid]);
+
+  const columnDefs = useMemo(
+    (): GridOptions["columnDefs"] => [
+      {
+        colId: "selection",
+        editable: false,
+        initialWidth: 35,
+        minWidth: 35,
+        maxWidth: 35,
+        suppressSizeToFit: true,
+        checkboxSelection: true,
+        headerComponent: GridHeaderSelect,
+        onCellClicked: clickSelectorCheckboxWhenContainingCellClicked,
+      },
+      ...(params.columnDefs as ColDef[]),
+    ],
+    [clickSelectorCheckboxWhenContainingCellClicked, params.columnDefs],
+  );
+
+  const onGridReady = useCallback(
+    (event: GridReadyEvent) => {
+      setGridApi(event.api);
+      params.onGridReady && params.onGridReady(event);
+      synchroniseExternallySelectedItemsToGrid();
+      updateQuickFilter();
+    },
+    [params, setGridApi, synchroniseExternallySelectedItemsToGrid, updateQuickFilter],
+  );
+
+  const noRowsOverlayComponent = useCallback(
+    () => (
+      <span className="ag-overlay-no-rows-center">{params.noRowsOverlayText ?? "There are currently no rows"}</span>
+    ),
+    [params.noRowsOverlayText],
+  );
+
+  const sizeColumnsToFit = useCallback((event: AgGridEvent) => {
+    // @ts-ignore (gridBodyCtrl is private)
+    if (event.api.gridBodyCtrl == undefined) {
+      return;
+      // this is here because ag grid was throwing api undefined error when closing POPPED OUT panel
+    }
+    event.api.sizeColumnsToFit();
+  }, []);
+
+  const refreshSelectedRows = useCallback((event: CellEvent): void => {
+    // Force-refresh all selected rows to re-run class function, to update selection highlighting
+    event.api.refreshCells({
+      force: true,
+      rowNodes: event.api.getSelectedNodes(),
+    });
+  }, []);
+
+  const startCellEditing = useCallback(
+    (event: CellEvent) => {
+      if (!event.node.isSelected()) {
+        event.node.setSelected(true, true);
+      }
+      // Cell already being edited, so don't re-edit until finished
+      if (checkUpdating([event.colDef.field ?? ""], event.data.id)) {
+        return;
+      }
+      if (event.rowIndex !== null) {
+        event.api.startEditingCell({
+          rowIndex: event.rowIndex,
+          colKey: event.column.getColId(),
+        });
+      }
+    },
+    [checkUpdating],
+  );
+
+  const onCellDoubleClick = useCallback(
+    (event: CellEvent) => {
+      if (!event.colDef?.cellRendererParams?.singleClickEdit) {
+        startCellEditing(event);
+      }
+    },
+    [startCellEditing],
+  );
+
+  const onCellClicked = useCallback(
+    (event: CellEvent) => {
+      if (event.colDef?.cellRendererParams?.singleClickEdit) {
+        startCellEditing(event);
+      }
+    },
+    [startCellEditing],
+  );
+
+  const onCellKeyDown = useCallback(
+    (e: CellEvent) => {
+      if ((e.event as KeyboardEvent).key === "Enter") startCellEditing(e);
+    },
+    [startCellEditing],
+  );
+
+  const onCellEditingStopped = useCallback(
+    (event: CellEvent) => {
+      refreshSelectedRows(event);
+      // The grid loses cell focus after editing
+      const cell = event.api.getFocusedCell();
+      cell && event.api.setFocusedCell(cell.rowIndex, cell.column);
+    },
+    [refreshSelectedRows],
+  );
+
+  return (
+    <div
+      data-testid={params.dataTestId}
+      className={clsx("Grid-container", "ag-theme-alpine", staleGrid && "Grid-sortIsStale")}
+    >
+      {params.quickFilter && (
+        <div className="Grid-quickFilter">
+          <input
+            aria-label="Search"
+            className="lui-margin-top-xxs lui-margin-bottom-xxs Grid-quickFilterBox"
+            type="text"
+            placeholder={params.quickFilterPlaceholder ?? "Search..."}
+            value={internalQuickFilter}
+            onChange={(event): void => {
+              setInternalQuickFilter(event.target.value);
+            }}
+          />
+        </div>
+      )}
+      <AgGridReact
+        getRowId={(params) => `${params.data.id}`}
+        suppressRowClickSelection={true}
+        rowSelection={"multiple"}
+        suppressBrowserResizeObserver={true}
+        colResizeDefault={"shift"}
+        onFirstDataRendered={sizeColumnsToFit}
+        onGridSizeChanged={sizeColumnsToFit}
+        suppressClickEdit={true}
+        onCellKeyDown={onCellKeyDown}
+        onCellClicked={onCellClicked}
+        onCellDoubleClicked={onCellDoubleClick}
+        onCellEditingStarted={refreshSelectedRows}
+        onCellEditingStopped={onCellEditingStopped}
+        columnDefs={columnDefs}
+        rowData={params.rowData}
+        noRowsOverlayComponent={noRowsOverlayComponent}
+        onGridReady={onGridReady}
+        onSortChanged={ensureSelectedRowIsVisible}
+        postSortRows={postSortRows}
+        onSelectionChanged={synchroniseExternalStateToGridSelection}
+      />
+    </div>
+  );
+};

package/src/components/GridCell.tsx

@@ -0,0 +1,101 @@
+import { useCallback, useContext, useMemo, useState } from "react";
+import { GridBaseRow } from "./Grid";
+import { GridContext } from "../contexts/GridContext";
+import { GenericMultiEditCellClass } from "./GenericCellClass";
+import { GenericCellRendererParams, GridRendererGenericCell } from "./gridRender/GridRenderGenericCell";
+import { ColDef, ICellEditorParams } from "ag-grid-community";
+
+export interface GridFormProps<RowType extends GridBaseRow> {
+  cellEditorParams: ICellEditorParams;
+  updateValue: (saveFn: (selectedRows: RowType[]) => Promise<boolean>) => Promise<boolean>;
+  saving: boolean;
+  value: any;
+  field: string | undefined;
+  selectedRows: RowType[];
+  formProps: Record<string, any>;
+}
+
+export interface GenericCellEditorParams<RowType extends GridBaseRow> {
+  multiEdit?: boolean;
+  form?: (props: GridFormProps<RowType>) => JSX.Element;
+}
+
+export interface GenericCellEditorColDef<
+  RowType extends GridBaseRow,
+  FormProps extends GenericCellEditorParams<RowType>,
+> extends ColDef {
+  cellEditorParams?: FormProps;
+  cellRendererParams?: GenericCellRendererParams;
+}
+
+/**
+ * For editing a text area.
+ */
+export const GridCell = <RowType extends GridBaseRow, FormProps extends GenericCellEditorParams<RowType>>(
+  props: GenericCellEditorColDef<RowType, FormProps>,
+): ColDef => {
+  return {
+    cellRenderer: props.cellRenderer ?? GridRendererGenericCell,
+    sortable: !!(props?.field || props?.valueGetter),
+    resizable: true,
+    ...(props.cellEditorParams && {
+      cellClass: props?.cellEditorParams?.multiEdit ? GenericMultiEditCellClass : undefined,
+      editable: true,
+      cellEditor: GenericCellEditorComponent,
+    }),
+    ...props,
+  };
+};
+
+interface GenericCellEditorICellEditorParams<RowType extends GridBaseRow, FormProps extends Record<string, any>>
+  extends ICellEditorParams {
+  data: RowType;
+  colDef: GenericCellEditorColDef<RowType, FormProps>;
+}
+
+export const GenericCellEditorComponent = <RowType extends GridBaseRow, FormProps extends Record<string, any>>(
+  props: GenericCellEditorICellEditorParams<RowType, FormProps>,
+) => {
+  const { updatingCells, getSelectedRows } = useContext(GridContext);
+
+  const { colDef, data } = props;
+  const { cellEditorParams } = props.colDef;
+  const multiEdit = cellEditorParams?.multiEdit ?? false;
+  const field = props.colDef.field ?? "";
+
+  const formProps = colDef.cellEditorParams ?? {};
+  const value = props.value;
+
+  const selectedRows = useMemo(
+    () => (multiEdit ? getSelectedRows<RowType>() : [data]),
+    [data, getSelectedRows, multiEdit],
+  );
+
+  const [saving, setSaving] = useState(false);
+
+  const updateValue = useCallback(
+    async (saveFn: (selectedRows: any[]) => Promise<boolean>): Promise<boolean> => {
+      return !saving && (await updatingCells({ selectedRows, field }, saveFn, setSaving));
+    },
+    [field, saving, selectedRows, updatingCells],
+  );
+
+  if (cellEditorParams == null) return <></>;
+
+  return (
+    <>
+      <div>{colDef.cellRenderer ? <colDef.cellRenderer {...props} saving={saving} /> : props.value}</div>
+      {cellEditorParams?.form && (
+        <cellEditorParams.form
+          cellEditorParams={props}
+          updateValue={updateValue}
+          saving={saving}
+          formProps={formProps}
+          value={value}
+          field={field}
+          selectedRows={selectedRows}
+        />
+      )}
+    </>
+  );
+};

package/src/components/GridIcon.tsx

@@ -0,0 +1,12 @@
+import { IconName } from "@linzjs/lui/dist/components/LuiIcon/LuiIcon";
+import { LuiIcon } from "@linzjs/lui";
+
+export const GridIcon = (props: { icon: IconName; title: string }): JSX.Element => (
+  <LuiIcon
+    name={props.icon}
+    title={props.title}
+    alt={props.title}
+    size={"md"}
+    className={`AgGridGenericCellRenderer-${props.icon}Icon`}
+  />
+);

package/src/components/GridLoadableCell.tsx

@@ -0,0 +1,22 @@
+import { LuiMiniSpinner } from "@linzjs/lui";
+
+export const GridLoadableCell = (props: {
+  isLoading: boolean;
+  dataTestId?: string;
+  children: JSX.Element | string;
+}): JSX.Element => {
+  // console.log(`Rendering LoadableCell - loading: ${props.isLoading}`);
+  if (props.isLoading) {
+    return (
+      <div style={{ display: "flex", alignItems: "center" }}>
+        <LuiMiniSpinner size={22} divProps={{ role: "status", "aria-label": "Loading", style: { marginBottom: 4 } }} />
+      </div>
+    );
+  }
+  // only add test id into ONE of the columns in a grid. this way each row will have one unique id :)
+  return (
+    <div data-testid={props.dataTestId} style={{ display: "flex", alignItems: "center" }}>
+      {props.children}
+    </div>
+  );
+};