playbook_ui 13.16.0.pre.alpha.PLAY11642006 → 13.16.0.pre.alpha.PLAY12002127

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,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_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.

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

@@ -0,0 +1,59 @@
+import React, { useState } from "react";
+import { AdvancedTable } from "../../";
+import { MOCK_DATA } from "./_mock_data";
+
+const AdvancedTableExpandedControl = (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",
+    },
+  ];
+
+  //State for manually effecting what is expanded
+  const [expanded, setExpanded] = useState({'0': true, '0.0': true, '0.0.1': true})
+
+  //Passing expanded state to AdvancedTable as prop
+  const expandedControl = {
+    value: expanded,
+    onChange: setExpanded,
+  }
+
+  return (
+    <div>
+      <AdvancedTable
+          columnDefinitions={columnDefinitions}
+          expandedControl={expandedControl}
+          tableData={MOCK_DATA}
+          {...props}
+      />
+    </div>
+  );
+};
+
+export default AdvancedTableExpandedControl;

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

@@ -0,0 +1,18 @@
+`expandedControl` is an optional prop that can be used to gain greater control over the expansion state of the Advanced Table. Tanstack handles expansion itself, however it does provide for a way to handle the state manually if needed. Usecases for this include needing to store the expansion state so it persists on page reload, set an initial expansion state, etc. 
+
+In this example we are showing that if initial expansion state is set, it will render the table expanded according to that state. 
+
+The expanded state must be an object with key/value pairs where the key is the row id and the value is a boolean, true or false. Tanstack by default assigns row ids based on index and depth of the row as can be seen in this example. For more information on row ids, see [here](https://tanstack.com/table/v8/docs/api/core/row#id).
+
+### Single Row Expansion
+
+By default, the click event on the row level toggleExpansion icon simply toggles the immediate sub rows open or closed. If you want to attach further logic to that button, the optional `onRowToggleClick` prop can be used. This click event provides one argument that can be hooked into: the current `row` object. Any additional functionality provided through this onClick will be applied in addition to the default.
+
+###  Multi-Row Expansion
+
+Similar to the row level click event, the default of the click event on the toggleExpansion buttons that render in the first column header (and the subRow Header rows if prop enabled) toggles all top level rows open and closed. If you want to attach further logic to that button, the optional `onToggleExpansionClick` prop can be used. This click event provides one argument that can be hooked into: the current `row` object. Any additional functionality provided through this onClick will be applied in addition to the default.
+
+### ToggleExpansionIcon
+
+`ToggleExpansionIcon` is another optional prop that can be used to customize the icon for the toggleExpansion button. This prop takes a string value with the default set to `arrows-from-line`. All strings must be valid FA icons.
+

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

@@ -0,0 +1,60 @@
+import React, { useState } from "react";
+import { AdvancedTable } from "../../";
+import { Button } from "../../"
+import { MOCK_DATA } from "./_mock_data";
+
+const AdvancedTableLoading = (props) => {
+
+const [isloading, setIsLoading] = useState(true)
+
+  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>
+      <Button marginBottom="md" 
+          onClick={()=> setIsLoading(!isloading)}
+          text="Toggle Loading State"
+          variant="secondary"
+          {...props}
+      />
+      <AdvancedTable
+          columnDefinitions={columnDefinitions}
+          loading={isloading}
+          tableData={MOCK_DATA}
+          {...props}
+      />
+    </div>
+  );
+};
+
+export default AdvancedTableLoading;

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

@@ -0,0 +1,3 @@
+the optional `loading` prop takes a boolean value that can be managed using state. If loading is true, the table will display the loading skeleton and once loading is false, the table will render with the data provided. 
+
+By default, the inital row count of the loading skeleton is set to 10. If you want more control over this initial row count, the optional `initialLoadingRowCount` prop can be used to to pass in a number. __NOTE__: This is only for the first render of the table, subsequent loading skeleton row count logic is handled within the kit itself.

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

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

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

@@ -0,0 +1,5 @@
+the `enableSorting` prop is a boolean prop set to false by default. If true, the table will add sort logic linked to the sort button in the header. Clicking the sort button will toggle sort between ascending and descending. Currently this sort functionality is only available on the first column.
+
+### sortIcon
+
+An optional prop, `sortIcon` allows you to customize your icon sets by passing it an array of any comma-separated pair of icon values. The first icon value will replace the kit's default icon when sort direction is desc, and the second value will replace the default icon when sort direction is asc. `sortIcon` also allows you to pass it a single icon as a string, in which case the icon will not toggle with the sort state. Default for this prop is `["arrow-up-short-wide", "arrow-down-short-wide"]`. All strings must be valid FA icons.

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

@@ -0,0 +1,63 @@
+import React, { useState } from "react";
+import { AdvancedTable } from "../..";
+import { MOCK_DATA } from "./_mock_data";
+
+const AdvancedTableSortControl = (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",
+    },
+  ];
+
+  //State for sort direction
+  const [isSortDesc, setIsSortDesc] = useState({desc: false})
+
+  // //Passing sort state to AdvancedTable as prop
+  const sortControl = {
+    value: isSortDesc,
+    onChange: setIsSortDesc,
+  }
+
+
+  return (
+    <div>
+      <AdvancedTable
+          columnDefinitions={columnDefinitions}
+          sortControl={sortControl}
+          tableData={MOCK_DATA}
+          {...props}
+      >
+        <AdvancedTable.Header enableSorting />
+        <AdvancedTable.Body />
+      </AdvancedTable>
+    </div>
+  );
+};
+
+export default AdvancedTableSortControl;