playbook_ui 13.15.0 → 13.16.0.pre.alpha.PBNTR177NewAdvancedTableKit2023

data/app/pb_kits/playbook/pb_advanced_table/SubKits/TableBody.tsx

@@ -0,0 +1,95 @@
+import React, { useContext } from "react"
+import LoadingInline from "../../pb_loading_inline/_loading_inline"
+import { flexRender, Row } from "@tanstack/react-table"
+
+import { SubRowHeaderRow } from "../Components/SubRowHeaderRow"
+import { LoadingCell } from "../Components/LoadingCell"
+import { renderCollapsibleTrail } from "../Components/CollapsibleTrail"
+import AdvancedTableContext from "../Context/AdvancedTableContext"
+import { isChrome } from "../Utilities/BrowserCheck"
+import { DataType } from "../Utilities/types"
+
+type TableBodyProps = {
+  collapsibleTrail?: boolean
+  subRowHeaders?: string[]
+}
+
+export const TableBody = ({
+  collapsibleTrail = true,
+  subRowHeaders,
+}: TableBodyProps) => {
+  const {
+    enableToggleExpansion,
+    handleExpandOrCollapse,
+    loading,
+    table,
+  } = useContext(AdvancedTableContext)
+  return (
+    <>
+      <tbody>
+        {table.getRowModel().rows.map((row: Row<DataType>) => {
+          const isExpandable = row.getIsExpanded()
+          const isFirstChildofSubrow = row.depth > 0 && row.index === 0
+          const rowHasNoChildren = !row.original.children?.length
+          const numberOfColumns = table.getAllFlatColumns().length
+
+          return (
+            <React.Fragment key={`${row.index}-${row.id}-${row.depth}-row`}>
+              {isFirstChildofSubrow && subRowHeaders && (
+                <SubRowHeaderRow
+                    collapsibleTrail={collapsibleTrail}
+                    enableToggleExpansion={enableToggleExpansion}
+                    onClick={handleExpandOrCollapse}
+                    row={row}
+                    subRowHeaders={subRowHeaders}
+                    table={table}
+                />
+              )}
+
+              <tr
+                  className={`${isExpandable ? "bg-silver" : "bg-white"} ${
+                    row.depth > 0 ? `depth-sub-row-${row.depth}` : ""
+                  }`}
+                  id={`${row.index}-${row.id}-${row.depth}-row`}
+              >
+                {row.getVisibleCells().map((cell, i) => (
+                  <td
+                      align="right"
+                      className={`${cell.id}-cell position_relative ${
+                      isChrome() ? "chrome-styles" : ""
+                      }`}
+                      key={`${cell.id}-data`}
+                  >
+                    {collapsibleTrail &&
+                      i === 0 &&
+                      row.depth > 0 &&
+                      renderCollapsibleTrail(row.depth)}
+                    <span id={`${cell.id}-span`}>
+                      {loading ? (
+                        <LoadingCell />
+                      ) : (
+                        flexRender(
+                          cell.column.columnDef.cell,
+                          cell.getContext()
+                        )
+                      )}
+                    </span>
+                  </td>
+                ))}
+              </tr>
+
+              {/* Display LoadingInline if Row Data is querying and there are no children already */}
+              {isExpandable && rowHasNoChildren && row.depth === 0 ? (
+                <tr key={`${row.id}-row`}>
+                  <td colSpan={numberOfColumns}>
+                    <LoadingInline />
+                  </td>
+                </tr>
+              ) : null}
+            </React.Fragment>
+          )
+        })}
+      </tbody>
+    </>
+  )
+}

data/app/pb_kits/playbook/pb_advanced_table/SubKits/TableHeader.tsx

@@ -0,0 +1,51 @@
+import React, { useContext } from "react"
+import { HeaderGroup } from "@tanstack/react-table"
+import AdvancedTableContext from "../Context/AdvancedTableContext"
+import { TableHeaderCell } from "../Components/TableHeaderCell"
+import { DataType } from "../Utilities/types"
+
+type TableHeaderProps = {
+  children?: React.ReactNode | React.ReactNode[]
+  enableSorting?: boolean
+  headerId?: string
+  sortIcon?: string | string[]
+}
+
+export const TableHeader = ({
+  children,
+  enableSorting = false,
+  headerId,
+  sortIcon = ["arrow-up-short-wide", "arrow-down-short-wide"],
+}: TableHeaderProps) => {
+  const {
+    enableToggleExpansion,
+    handleExpandOrCollapse,
+    loading,
+    table,
+  } = useContext(AdvancedTableContext)
+
+  return (
+    <>
+      <thead>
+        {/* Get the header groups (only one in this example) */}
+        {table.getHeaderGroups().map((headerGroup: HeaderGroup<DataType>) => (
+          <tr key={`${headerGroup.id}-headerGroup`}>
+            {headerGroup.headers.map(header => (
+              <TableHeaderCell
+                  enableSorting={enableSorting}
+                  enableToggleExpansion={enableToggleExpansion}
+                  handleExpandOrCollapse={handleExpandOrCollapse}
+                  header={header}
+                  headerChildren={children}
+                  headerId={headerId}
+                  key={`${header.id}-header`}
+                  loading={loading}
+                  sortIcon={sortIcon}
+              />
+            ))}
+          </tr>
+        ))}
+      </thead>
+    </>
+  )
+}

data/app/pb_kits/playbook/pb_advanced_table/Utilities/BrowserCheck.tsx

@@ -0,0 +1,5 @@
+//Checking browser. Using this to add classname and css for browser specific issues with table borders
+export const isChrome = () => {
+  const userAgent = navigator.userAgent.toLowerCase()
+  return userAgent.includes("chrome") && !userAgent.includes("edg")
+}

data/app/pb_kits/playbook/pb_advanced_table/Utilities/ExpansionControlHelpers.tsx

@@ -0,0 +1,63 @@
+import { RowModel } from "@tanstack/react-table"
+import { DataType, ExpandedStateObject } from "./types"
+
+const filterExpandableRows = (expandedState: Record<string, boolean>) => {
+  for (const expandedRow in expandedState) {
+    if (expandedState[expandedRow] === false) {
+      delete expandedState[expandedRow]
+    }
+  }
+  return expandedState
+}
+
+export const updateExpandAndCollapseState = (
+  tableRows: RowModel<DataType>,
+  expanded: Record<string, boolean>,
+  targetParent: string
+) => {
+  const updateExpandedRows: Record<string, boolean> = {}
+  const rows = tableRows.flatRows
+  // Variable checks if all rows in a section have same expansion state or not
+  let isExpansionConsistent = true
+  const areRowsExpanded = new Set<boolean>()
+
+  // Update isExpansionConsistent variable
+  for (const row of rows) {
+    if (
+      row.getCanExpand() &&
+      (targetParent === undefined
+        ? row.depth === 0
+        : targetParent === row.parentId)
+    ) {
+      areRowsExpanded.add(row.getIsExpanded())
+      if (areRowsExpanded.size > 1) {
+        isExpansionConsistent = false
+        break
+      }
+    }
+  }
+
+  // The if statement runs only for row depth 0, the else statement for the rest
+  if (targetParent === undefined) {
+    rows.forEach(row => {
+      if (row.depth === 0) {
+        updateExpandedRows[row.id] = !isExpansionConsistent
+          ? true
+          : !row.getIsExpanded()
+      }
+    })
+  } else {
+    for (const row of rows) {
+      if (row.getCanExpand() && targetParent === row.parentId) {
+        updateExpandedRows[row.id] = !isExpansionConsistent
+          ? true
+          : !row.getIsExpanded()
+      }
+    }
+  }
+
+  return filterExpandableRows({
+    ...(expanded as ExpandedStateObject),
+    ...updateExpandedRows,
+  })
+}

data/app/pb_kits/playbook/pb_advanced_table/Utilities/IconHelpers.tsx

@@ -0,0 +1,8 @@
+// Logic for handling icons related props to allow for string OR array of strings
+export const displayIcon = (icon: string | string[]) => {
+    if (typeof icon === "string") {
+      return [icon, icon]
+    }
+    return icon
+  }
+  

data/app/pb_kits/playbook/pb_advanced_table/Utilities/types.ts

@@ -0,0 +1,8 @@
+import { ExpandedState } from "@tanstack/react-table"
+
+export type ExpandedStateObject = Extract<
+  ExpandedState,
+  Record<string, boolean>
+>
+
+export type DataType = { [key: string]: any }

data/app/pb_kits/playbook/pb_advanced_table/_advanced_table.scss

@@ -0,0 +1,98 @@
+@import "../tokens/colors";
+@import "../tokens/opacity";
+@import "../tokens/border_radius";
+@import "../tokens/spacing";
+@import "./scss_partials/loading";
+@import "./scss_partials/pseudo_states";
+
+.pb_advanced_table {
+  $border-color: 1px solid $border_light !important;
+
+  [id$="-span"] {
+    word-wrap: normal;
+  }
+
+  .bg-silver {
+    background-color: lighten($silver, $opacity_7);
+  }
+
+  .bg-white {
+    background-color: $white;
+  }
+
+  .full-width {
+    width: 100%;
+  }
+
+  .table-header-cells:first-child {
+    min-width: 180px;
+  }
+
+  .table-header-cells-active:first-child {
+    color: $primary !important;
+  }
+
+  // Icons
+  .button-icon {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    background: none;
+    border: none;
+  }
+
+  .gray-icon {
+    color: $text_lt_light;
+    @extend %primary-color-pseudo;
+  }
+
+  .year-sort-icon {
+    @extend .button-icon;
+    padding: 2px;
+  }
+
+  .time-period-toggle-icon {
+    @extend .button-icon;
+    @extend %primary-color-pseudo;
+    padding: 2px 0;
+
+    &:focus-visible {
+      border-radius: $border_rad_lighter;
+    }
+  }
+
+  .expand-toggle-icon {
+    @extend .button-icon;
+    @extend %primary-color-pseudo;
+    position: relative;
+    bottom: 1px;
+    width: 18px;
+    height: 18px;
+    border-radius: 50%;
+  }
+
+  .header-sort-button {
+    @extend %primary-color-pseudo;
+    width: 100%;
+
+    &:focus-visible {
+      border-radius: $border_rad_heavier;
+    }
+  }
+
+  // Vertical separator
+  .table-header-cells:first-child,
+  td:first-child {
+    box-shadow: 1px 0px 0px 0px #e4e8f0 !important;
+  }
+
+  .chrome-styles:first-child {
+    border-right: $border-color;
+  }
+
+  .table-card {
+    .chrome-styles:first-child {
+      border-right: $transparent !important;
+    }
+  }
+}

data/app/pb_kits/playbook/pb_advanced_table/_advanced_table.tsx

@@ -0,0 +1,245 @@
+import React, { useState, useEffect, useCallback } from "react";
+import classnames from "classnames";
+import { buildAriaProps, buildCss, buildDataProps } from "../utilities/props";
+import { globalProps, GlobalProps } from "../utilities/globalProps";
+import Table from "../pb_table/_table";
+import {
+  createColumnHelper,
+  getCoreRowModel,
+  getExpandedRowModel,
+  getSortedRowModel,
+  Row,
+  useReactTable,
+  Getter,
+} from "@tanstack/react-table";
+
+import { updateExpandAndCollapseState } from "./Utilities/ExpansionControlHelpers";
+
+import { CustomCell } from "./Components/CustomCell";
+import AdvancedTableContext from "./Context/AdvancedTableContext";
+import { TableHeader } from "./SubKits/TableHeader";
+import { TableBody } from "./SubKits/TableBody";
+
+import { DataType, ExpandedStateObject } from "./Utilities/types";
+
+type AdvancedTableProps = {
+  aria?: { [key: string]: string };
+  children?: React.ReactNode | React.ReactNode[];
+  className?: string;
+  columnDefinitions: DataType[];
+  data?: { [key: string]: string };
+  enableToggleExpansion?: "all" | "header";
+  expandedControl?: DataType;
+  id?: string;
+  initialLoadingRowsCount?: number;
+  loading?: boolean | string;
+  onRowToggleClick?: (arg: Row<DataType>) => void;
+  onToggleExpansionClick?: (arg: Row<DataType>) => void;
+  sortControl?: DataType;
+  tableData: DataType[];
+  tableOptions?: DataType;
+  tableProps?: DataType;
+  toggleExpansionIcon?: string | string[];
+} & GlobalProps;
+
+const AdvancedTable = (props: AdvancedTableProps) => {
+  const {
+    aria = {},
+    children,
+    className,
+    columnDefinitions,
+    data = {},
+    enableToggleExpansion = "header",
+    expandedControl,
+    id,
+    initialLoadingRowsCount = 10,
+    loading,
+    onRowToggleClick,
+    onToggleExpansionClick,
+    sortControl,
+    tableData,
+    tableOptions,
+    tableProps,
+    toggleExpansionIcon = "arrows-from-line",
+  } = props;
+
+  const [loadingStateRowCount, setLoadingStateRowCount] = useState(
+    initialLoadingRowsCount
+  );
+
+  // Create a local state for expanded and setExpanded if expandedControl not used
+  const [localExpanded, setLocalExpanded] = useState({});
+
+  // Determine whether to use the prop or the local state
+  const expanded = expandedControl ? expandedControl.value : localExpanded;
+  const setExpanded = expandedControl
+    ? expandedControl.onChange
+    : setLocalExpanded;
+
+  const columnHelper = createColumnHelper<DataType>();
+
+  //Create cells for first columns
+  const createCellFunction = (cellAccessors: string[]) => {
+    const columnCells = ({
+      row,
+      getValue,
+    }: {
+      row: Row<DataType>;
+      getValue: Getter<string>;
+    }) => {
+      const rowData = row.original;
+
+      switch (row.depth) {
+        case 0: {
+          return (
+            <CustomCell
+                getValue={getValue}
+                onRowToggleClick={onRowToggleClick}
+                row={row}
+            />
+          );
+        }
+        default: {
+          // Handle other depths based on cellAccessors
+          const depthAccessor = cellAccessors[row.depth - 1]; // Adjust index for depth
+          const accessorValue = rowData[depthAccessor];
+          return accessorValue ? (
+            <CustomCell row={row} 
+                value={accessorValue} 
+            />
+          ) : (
+            "N/A"
+          );
+        }
+      }
+    };
+
+    return columnCells;
+  };
+
+  //Create column array in format needed by Tanstack
+  const columns =
+    columnDefinitions &&
+    columnDefinitions.map((column) => {
+      // Define the base column structure
+      const columnStructure = {
+        ...columnHelper.accessor(column.accessor, {
+          header: column.label,
+        }),
+      };
+      if (column.cellAccessors) {
+        columnStructure.cell = createCellFunction(column.cellAccessors);
+      }
+      return columnStructure;
+    });
+
+  //Syntax for sorting Array if we want to manage state ourselves
+  const sorting = [
+    {
+      id: columnDefinitions[0].accessor,
+      desc:
+        sortControl && sortControl.value !== null
+          ? !sortControl.value.desc
+          : false,
+    },
+  ];
+
+  const expandAndSortState = () => {
+    if (sortControl) {
+      return { state: { expanded, sorting } };
+    } else {
+      return { state: { expanded } };
+    }
+  };
+
+//initialize table
+  const table = useReactTable({
+    data: loading ? Array(loadingStateRowCount).fill({}) : tableData,
+    columns,
+    onExpandedChange: setExpanded,
+    getSubRows: (row) => row.children,
+    getCoreRowModel: getCoreRowModel(),
+    getExpandedRowModel: getExpandedRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    enableSortingRemoval: false,
+    ...expandAndSortState(),
+    ...tableOptions,
+  });
+
+  const tableRows = table.getRowModel();
+
+  // Set table row count for loading state
+  const updateLoadingStateRowCount = useCallback(() => {
+    const rowsCount = table.getRowModel().rows.length;
+    if (rowsCount !== loadingStateRowCount && rowsCount !== 0) {
+      setLoadingStateRowCount(rowsCount);
+    }
+  }, [tableData, loadingStateRowCount]);
+
+  useEffect(() => {
+    if (!loading) {
+      updateLoadingStateRowCount();
+    }
+  }, [loading, updateLoadingStateRowCount]);
+
+  const handleExpandOrCollapse = (row: Row<DataType>) => {
+    onToggleExpansionClick && onToggleExpansionClick(row);
+
+    const expandedState = expanded as ExpandedStateObject;
+    const targetParent = row?.parentId;
+    return setExpanded(
+      updateExpandAndCollapseState(tableRows, expandedState, targetParent)
+    );
+  };
+
+  const ariaProps = buildAriaProps(aria);
+  const dataProps = buildDataProps(data);
+  const classes = classnames(
+    buildCss("pb_advanced_table"),
+    globalProps(props),
+    className
+  );
+
+  return (
+    <div {...ariaProps} 
+        {...dataProps} 
+        className={classes} 
+        id={id}
+    >
+      <AdvancedTableContext.Provider
+          value={{
+            table,
+            handleExpandOrCollapse,
+            loading,
+            enableToggleExpansion,
+            toggleExpansionIcon,
+            setExpanded,
+            expanded,
+            sortControl,
+          }}
+      >
+        <Table
+            className={`${loading ? "content-loading" : ""}`}
+            dataTable
+            numberSpacing="tabular"
+            responsive="none"
+            {...tableProps}
+        >
+          {children ? (
+            children
+          ) : (
+            <>
+              <TableHeader />
+              <TableBody />
+            </>
+          )}
+        </Table>
+      </AdvancedTableContext.Provider>
+    </div>
+  );
+};
+
+AdvancedTable.Header = TableHeader;
+AdvancedTable.Body = TableBody;
+
+export default AdvancedTable;

data/app/pb_kits/playbook/pb_advanced_table/advanced_table.test.jsx

@@ -0,0 +1,56 @@
+import React from "react";
+import { render, screen } from "../utilities/test-utils";
+
+import { AdvancedTable } from "../";
+
+const MOCK_DATA = [
+  {
+    year: "2021",
+    quarter: null,
+    month: null,
+    day: null,
+    newEnrollments: "20",
+    scheduledMeetings: "10",
+    children: [
+      {
+        year: "2011",
+        quarter: "Q1",
+        month: null,
+        day: null,
+        newEnrollments: "2",
+        scheduledMeetings: "35",
+      },
+    ],
+  },
+];
+
+const columnDefinitions = [
+  {
+    accessor: "year",
+    label: "Year",
+    cellAccessors: ["quarter", "month", "day"],
+  },
+  {
+    accessor: "newEnrollments",
+    label: "New Enrollments",
+  },
+  {
+    accessor: "scheduledMeetings",
+    label: "Scheduled Meetings",
+  },
+];
+
+const testId = "advanced_table";
+
+test("generated scaffold test", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        tableData={MOCK_DATA}
+    />
+  );
+
+  const kit = screen.getByTestId(testId);
+  expect(kit).toBeInTheDocument();
+});

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_default.jsx

@@ -0,0 +1,49 @@
+import React from "react";
+import { AdvancedTable } from "../../";
+import { MOCK_DATA } from "./_mock_data";
+
+const AdvancedTableDefault = (props) => {
+  const columnDefinitions = [
+    {
+      accessor: "year",
+      label: "Year",
+      cellAccessors: ["quarter", "month", "day"],
+    },
+    {
+      accessor: "newEnrollments",
+      label: "New Enrollments",
+    },
+    {
+      accessor: "scheduledMeetings",
+      label: "Scheduled Meetings",
+    },
+    {
+      accessor: "attendanceRate",
+      label: "Attendance Rate",
+    },
+    {
+      accessor: "completedClasses",
+      label: "Completed Classes",
+    },
+    {
+      accessor: "classCompletionRate",
+      label: "Class Completion Rate",
+    },
+    {
+      accessor: "graduatedStudents",
+      label: "Graduated Students",
+    },
+  ];
+
+  return (
+    <div>
+      <AdvancedTable
+          columnDefinitions={columnDefinitions}
+          tableData={MOCK_DATA}
+          {...props}
+      />
+    </div>
+  );
+};
+
+export default AdvancedTableDefault;

data/app/pb_kits/playbook/pb_advanced_table/docs/_advanced_table_default.md

@@ -0,0 +1,13 @@
+The AdvancedTable kit takes the table data and automatically renders expandable subrows for nested items to any depth needed. In it's simplest form, the kit has two required props: 
+
+`tableData` is the data that the kit needs to consume to render the table. This data will take the structure of an array of objects where each object will be rendered as a row with the key/value pairs being the column values. If an object within that data has children, the kit will automatically create subRows with icon buttons on the parent rows to toggle the subRows open or closed. The toggleExpansionAll button in the first column header can also be used to toggle expansion for the top level parent rows. For a visual of the data structure needed for `tableData`, see [here](https://github.com/powerhome/playbook/blob/1b2481c06137d2bc63031a1120c1bd4d01bfd9ec/playbook/app/pb_kits/playbook/pb_advanced_table/README.md).
+
+
+`columnDefinitions` maps to the columns prop on the Tanstack table. Column definitions are the single most important part of building a table as they are responsible for building the underlying data model that is used for all sorting, expansion, etc. `ColumnDefinitions` in the AdvancedTable kit is a array of objects as seen in the code snippet below. Each object within the array has two REQUIRED items:
+
+- `accessor`: this is the key from your data for the value you want rendered in that column
+- `label`: this is what will be rendered as the column header label
+
+There is also one optional item that is only required if the table has nested data: 
+
+- `cellAccessors`: This is an array of strings that represent keys from your data object. This is only required for the first column in case of nested data. If you have nested data, the AdvancedTable needs to know what to render in that first column for nested items. This array represents the nested data in the order you want it rendered.