playbook_ui 13.16.0 → 13.18.0

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

@@ -0,0 +1,246 @@
+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,
+    sortDescFirst: true,
+    ...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,345 @@
+import React, {useState} 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: "2021",
+        quarter: "Q1",
+        month: null,
+        day: null,
+        newEnrollments: "2",
+        scheduledMeetings: "35",
+      },
+    ],
+  },
+  {
+    year: "2022",
+    quarter: null,
+    month: null,
+    day: null,
+    newEnrollments: "20",
+    scheduledMeetings: "10",
+    children: [
+      {
+        year: "2022",
+        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 subRowHeaders = ["Quarter"]
+
+const testId = "advanced_table";
+
+const AdvancedTableExpandControl = () => {
+  const [expanded, setExpanded] = useState({'0': true})
+
+  const expandedControl = {
+    value: expanded,
+    onChange: setExpanded,
+  }
+
+return (
+  <div>
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        expandedControl={expandedControl}
+        tableData={MOCK_DATA}
+    />
+  </div>
+);
+}
+
+const AdvancedTableSortControl = () => {
+  const [isSortDesc, setIsSortDesc] = useState({desc: false})
+
+  const sortControl = {
+    value: isSortDesc,
+    onChange: setIsSortDesc,
+  }
+
+return (
+  <div>
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{testid: testId}}
+        sortControl={sortControl}
+        tableData={MOCK_DATA}
+      >
+        <AdvancedTable.Header enableSorting />
+        <AdvancedTable.Body />
+      </AdvancedTable>
+  </div>
+);
+}
+
+const tableOptions = {
+  initialState: {
+      sorting: [
+        {
+          id: "year",
+          desc: true,
+        },
+      ],
+    },
+}
+
+const tableProps = {
+  container: false,
+  sticky: true
+}
+
+test("Generates default kit and classname", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        tableData={MOCK_DATA}
+    />
+  );
+
+  const kit = screen.getByTestId(testId);
+  expect(kit).toBeInTheDocument();
+  expect(kit).toHaveClass('pb_advanced_table')
+});
+
+test("Generates aria label", () => {
+  render(
+    <AdvancedTable
+        aria={{label:testId}}
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        tableData={MOCK_DATA}
+    />
+  );
+
+  const kit = screen.getByTestId(testId);
+  expect(kit).toHaveAttribute('aria-label', testId)
+});
+
+test("Row toggle button exists and toggles subrows open and closed", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        tableData={MOCK_DATA}
+    />
+  );
+
+  const kit = screen.getByTestId(testId);
+  const rowButton = kit.querySelector(".gray-icon.expand-toggle-icon")
+  expect(rowButton).toBeInTheDocument()
+  const subRow1 = kit.querySelector(".bg-white.depth-sub-row-1")
+  expect(subRow1).not.toBeInTheDocument()
+  rowButton.click()
+  const subRow = kit.querySelector(".bg-white.depth-sub-row-1")
+  expect(subRow).toBeInTheDocument()
+});
+
+test("toggleExpansionAll button exists and toggles subrows open and closed", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        tableData={MOCK_DATA}
+    />
+  );
+
+  const kit = screen.getByTestId(testId);
+  const toggleButton = kit.querySelector(".gray-icon.toggle-all-icon")
+  expect(toggleButton).toBeInTheDocument()
+  const subRow1 = kit.querySelector(".bg-white.depth-sub-row-1")
+  expect(subRow1).not.toBeInTheDocument()
+  toggleButton.click()
+  const subRow = kit.querySelector(".bg-white.depth-sub-row-1")
+  expect(subRow).toBeInTheDocument()
+});
+
+test("loading state + initialLoadingRowCount prop", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        initialLoadingRowsCount={13}
+        loading
+        tableData={MOCK_DATA}
+    />
+  );
+
+  const kit = screen.getByTestId(testId);
+  const table = kit.querySelector('table')
+  expect(table).toHaveClass('pb_table table-sm table-responsive-none table-card data_table ns_tabular content-loading')
+
+  const tableBody = kit.querySelector('tbody')
+  const tableRows = tableBody.getElementsByTagName('tr')
+  expect(tableRows).toHaveLength(13)
+});
+
+test("subRowHeaders are rendered", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        tableData={MOCK_DATA}
+    >
+      <AdvancedTable.Header />
+      <AdvancedTable.Body subRowHeaders={subRowHeaders}/>
+    </AdvancedTable>
+    );
+
+  const kit = screen.getByTestId(testId);
+
+  const rowButton = kit.querySelector(".gray-icon.expand-toggle-icon")
+  rowButton.click()
+  
+  const subRowHeader = kit.querySelector(".custom-row.bg-silver")
+  expect(subRowHeader).toBeInTheDocument()
+});
+
+test("expandControl prop works as expected", () => {
+  render (<AdvancedTableExpandControl/>)
+
+  const kit = screen.getByTestId(testId);
+  const subRow = kit.querySelector(".bg-white.depth-sub-row-1")
+  expect(subRow).toBeInTheDocument()
+})
+
+test("tableOptions prop functions as expected", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        tableData={MOCK_DATA}
+        tableOptions={tableOptions}
+    />
+  );
+
+  const kit = screen.getByTestId(testId);
+  const row1 = kit.getElementsByTagName('tr')[1]
+  
+  expect(row1.id).toBe("1-1-0-row")
+});
+
+test("tableProps prop functions as expected", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        tableData={MOCK_DATA}
+        tableProps={tableProps}
+    />
+  );
+
+  const kit = screen.getByTestId(testId);
+  const table = kit.querySelector('table')
+  expect(table).toHaveClass("pb_table table-sm table-responsive-none data_table sticky-header ns_tabular")
+});
+
+test("enableExpansionIcon changes icon", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        tableData={MOCK_DATA}
+        tableProps={tableProps}
+        toggleExpansionIcon= "chevron-up"
+    />
+  );
+
+  const kit = screen.getByTestId(testId);
+  const tableHead = kit.querySelector('table')
+  const toggleIcon= tableHead.querySelector(".pb_icon_kit")
+  expect(toggleIcon).toHaveClass("fa-chevron-up")
+});
+
+test("sortIcon changes icon", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        tableData={MOCK_DATA}
+        tableProps={tableProps}
+    >
+      <AdvancedTable.Header 
+          enableSorting
+          sortIcon= {["chevron-up","chevron-down"]}
+      />
+      <AdvancedTable.Body />
+    </AdvancedTable>
+  );
+
+  const kit = screen.getByTestId(testId);
+  const sortIcon = kit.querySelector('.sort-button-icon')
+  const icon= sortIcon.querySelector(".pb_icon_kit")
+  expect(icon).toHaveClass("fa-chevron-down")
+});
+
+test("Sort icon renders with enableSorting + sortControl works as expected", () => {
+  render (<AdvancedTableSortControl/>)
+
+  const kit = screen.getByTestId(testId);
+  const sortIcon = kit.querySelector(".sort-button-icon")
+  expect(sortIcon).toBeInTheDocument()
+
+  const row1 = kit.getElementsByTagName('tr')[1]
+  
+  expect(row1.id).toBe("1-1-0-row")
+})
+
+test("sort button exists and sorts column data", () => {
+  render(
+    <AdvancedTable
+        columnDefinitions={columnDefinitions}
+        data={{ testid: testId }}
+        tableData={MOCK_DATA}
+    >
+      <AdvancedTable.Header enableSorting />
+      <AdvancedTable.Body />
+    </AdvancedTable>
+  );
+
+  const kit = screen.getByTestId(testId);
+
+  const sortButton= kit.querySelector(".pb_flex_kit_orientation_row_justify_content_between_align_items_top_spacing_none.pl_xxs.cursor_pointer.header-sort-button.pb_th_link")
+  expect(sortButton).toBeInTheDocument()
+
+  const row1 = kit.getElementsByTagName('tr')[1]
+  
+  expect(row1.id).toBe("0-0-0-row")
+  sortButton.click()
+
+  const row2 = kit.getElementsByTagName('tr')[2]
+  expect(row2.id).toBe("0-0-0-row")
+}); 

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

@@ -0,0 +1,52 @@
+import React from "react";
+import { AdvancedTable } from "../../";
+import { MOCK_DATA } from "./_mock_data";
+
+const AdvancedTableCollapsibleTrail = (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}
+      >
+        <AdvancedTable.Header />
+        <AdvancedTable.Body collapsibleTrail={false} />
+      </AdvancedTable>
+    </div>
+  );
+};
+
+export default AdvancedTableCollapsibleTrail;

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

@@ -0,0 +1 @@
+`collapsibleTrail` is an optional prop that is set to 'true' by default. If set to 'false', it will remove the trail on the left of rows when subRows are toggled open.

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,18 @@
+The AdvancedTable kit accepts tree data and automatically renders expansion controls for nested subrows, to any depth, based on the data it is given. In it's simplest form, __the kit has two required props__: 
+
+### tableData
+
+`tableData` accepts an array of objects as the table data. Each object is a table row, and each key:value pair within an object is a column value within that row. Nested children within a data object are automatically rendered as subrows under their parent row. Each parent row is prepended with expansion controls for toggling its nested child rows. The `toggleExpansionAll` button in the first column header can also be used to toggle expansion of all parent rows within the table.
+
+For a visual of the data structure needed for `tableData`, see [here](https://github.com/powerhome/playbook/tree/master/playbook/app/pb_kits/playbook/pb_advanced_table#readme).
+
+### columnDefinitions
+
+`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.