@proofkit/cli 1.0.0-beta.0

package/template/nextjs/tsconfig.json

@@ -0,0 +1,40 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    },
+    "target": "ES2017"
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/template/pages/nextjs/blank/page.tsx

@@ -0,0 +1,5 @@
+import React from "react";
+
+export default function BlankPage() {
+  return <div>BlankPage</div>;
+}

package/template/pages/nextjs/table/page.tsx

@@ -0,0 +1,17 @@
+import { __CLIENT_NAME__ } from "@/config/schemas/__SOURCE_NAME__/client";
+import { Stack } from "@mantine/core";
+import React from "react";
+
+import TableContent from "./table";
+
+export default async function TablePage() {
+  // this function is limited to 100 records by default. To load more, see the other table templates from the docs
+  const { data } = await __CLIENT_NAME__.list({
+    fetch: { next: { revalidate: 60 } }, // only call the database at most once every 60 seconds
+  });
+  return (
+    <Stack>
+      <TableContent data={data.map((d) => d.fieldData)} />
+    </Stack>
+  );
+}

package/template/pages/nextjs/table/table.tsx

@@ -0,0 +1,18 @@
+"use client";
+
+import { __TYPE_NAME__ } from "@/config/schemas/__SOURCE_NAME__/__SCHEMA_NAME__";
+import {
+  MantineReactTable,
+  MRT_ColumnDef,
+  useMantineReactTable,
+} from "mantine-react-table";
+import React from "react";
+
+type TData = __TYPE_NAME__;
+
+const columns: MRT_ColumnDef<TData>[] = [];
+
+export default function MyTable({ data }: { data: TData[] }) {
+  const table = useMantineReactTable({ data, columns });
+  return <MantineReactTable table={table} />;
+}

package/template/pages/nextjs/table-edit/actions.ts

@@ -0,0 +1,23 @@
+"use server";
+
+import { __CLIENT_NAME__ } from "@/config/schemas/__SOURCE_NAME__/client";
+import { __ZOD_TYPE_NAME__ } from "@/config/schemas/__SOURCE_NAME__/__SCHEMA_NAME__";
+import { __ACTION_CLIENT__ } from "@/server/safe-action";
+import { idFieldName } from "./schema";
+
+export const updateRecord = __ACTION_CLIENT__
+  .schema(__ZOD_TYPE_NAME__.partial())
+  .action(async ({ parsedInput }) => {
+    const id = parsedInput[idFieldName];
+    delete parsedInput[idFieldName]; // this ensures the id field value is not included in the updated fieldData
+    const data = parsedInput;
+
+    const {
+      data: { recordId },
+    } = await __CLIENT_NAME__.findOne({ query: { [idFieldName]: `==${id}` } });
+
+    return await __CLIENT_NAME__.update({
+      recordId,
+      fieldData: data,
+    });
+  });

package/template/pages/nextjs/table-edit/page.tsx

@@ -0,0 +1,28 @@
+import { __CLIENT_NAME__ } from "@/config/schemas/__SOURCE_NAME__/client";
+import { Stack, Text, Code } from "@mantine/core";
+import React from "react";
+
+import TableContent from "./table";
+import { idFieldName } from "./schema";
+
+export default async function TablePage() {
+  // this function is limited to 100 records by default. To load more, see the other table templates from the docs
+  const { data } = await __CLIENT_NAME__.list({
+    fetch: { next: { revalidate: 60 } }, // only call the database at most once every 60 seconds
+  });
+  return (
+    <Stack>
+      <div>
+        <Text>
+          This table allows editing. Double-click on a cell to edit the value.
+        </Text>
+        <Text size="sm" c="dimmed">
+          NOTE: This feature requires a primary key field on your API layout. If your
+          primary key field is not <Code>{idFieldName}</Code>, update the
+          <Code>idFieldName</Code> variable in the <Code>schema.ts</Code> file.
+        </Text>
+      </div>
+      <TableContent data={data.map((d) => d.fieldData)} />
+    </Stack>
+  );
+}

package/template/pages/nextjs/table-edit/schema.ts

@@ -0,0 +1,4 @@
+import { type __TYPE_NAME__ } from "@/config/schemas/__SOURCE_NAME__/__SCHEMA_NAME__";
+
+// TODO: Make sure this variable is properly set to your primary key field
+export const idFieldName: keyof __TYPE_NAME__ = "__FIRST_FIELD_NAME__";

package/template/pages/nextjs/table-edit/table.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { type __TYPE_NAME__ } from "@/config/schemas/__SOURCE_NAME__/__SCHEMA_NAME__";
+import {
+  MantineReactTable,
+  type MRT_Cell,
+  type MRT_ColumnDef,
+  useMantineReactTable,
+} from "mantine-react-table";
+import React from "react";
+import { updateRecord } from "./actions";
+import { showErrorNotification } from "@/utils/notification-helpers";
+import { idFieldName } from "./schema";
+
+type TData = __TYPE_NAME__;
+
+const columns: MRT_ColumnDef<TData>[] = [];
+
+async function handleSaveCell(cell: MRT_Cell<TData>, value: unknown) {
+  const resp = await updateRecord({
+    [idFieldName]: cell.row.id,
+    [cell.column.id]: value,
+  });
+  if (!resp?.data) {
+    showErrorNotification("Failed to update record");
+  }
+}
+
+export default function MyTable({ data }: { data: TData[] }) {
+  const table = useMantineReactTable({
+    data,
+    columns,
+    enableEditing: true,
+    editDisplayMode: "cell",
+    getRowId: (row) => row[idFieldName],
+    mantineEditTextInputProps: ({ cell }) => ({
+      //onBlur is more efficient, but could use onChange instead
+      onBlur: (event) => {
+        handleSaveCell(cell, event.target.value);
+      },
+    }),
+  });  return <MantineReactTable table={table} />;
+}

package/template/pages/nextjs/table-infinite/actions.ts

@@ -0,0 +1,62 @@
+"use server";
+
+import { __TYPE_NAME__ } from "@/config/schemas/__SOURCE_NAME__/__SCHEMA_NAME__";
+import { __CLIENT_NAME__ } from "@/config/schemas/__SOURCE_NAME__/client";
+import { __ACTION_CLIENT__ } from "@/server/safe-action";
+import { ListParams, Query } from "@proofkit/fmdapi/dist/client-types.js";
+import dayjs from "dayjs";
+import { z } from "zod/v4";
+
+const limit = 50; // raise or lower this number depending on how your layout performs
+export const fetchData = __ACTION_CLIENT__
+  .schema(
+    z.object({
+      offset: z.number().catch(0),
+      sorting: z.array(
+        z.object({ id: z.string(), desc: z.boolean().default(false) })
+      ),
+      columnFilters: z.array(z.object({ id: z.string(), value: z.unknown() })),
+    })
+  )
+  .action(async ({ parsedInput: { offset, sorting, columnFilters } }) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const getOptions: ListParams<__TYPE_NAME__, any> & {
+      query: Query<__TYPE_NAME__>[];
+    } = {
+      limit,
+      offset,
+      query: [{ ["__FIRST_FIELD_NAME__"]: "*" }],
+    };
+
+    if (sorting.length > 0) {
+      getOptions.sort = sorting.map(({ id, desc }) => ({
+        fieldName: id as keyof __TYPE_NAME__,
+        sortOrder: desc ? "descend" : "ascend",
+      }));
+    }
+
+    if (columnFilters.length > 0) {
+      getOptions.query = columnFilters
+        .map(({ id, value }) => {
+          if (typeof value === "string") {
+            return {
+              [id]: value,
+            };
+          } else if (typeof value === "object" && value instanceof Date) {
+            return {
+              [id]: dayjs(value).format("YYYY+MM+DD"),
+            };
+          }
+          return null;
+        })
+        .filter(Boolean) as Query<any>[];
+    }
+
+    const data = await __CLIENT_NAME__.find(getOptions);
+
+    return {
+      data: data.data,
+      hasNextPage: data.dataInfo.foundCount > limit + offset,
+      totalCount: data.dataInfo.foundCount,
+    };
+  });

package/template/pages/nextjs/table-infinite/page.tsx

@@ -0,0 +1,11 @@
+import { Stack } from "@mantine/core";
+
+import MyTable from "./table";
+
+export default async function TablePage() {
+  return (
+    <Stack>
+      <MyTable />
+    </Stack>
+  );
+}

package/template/pages/nextjs/table-infinite/query.ts

@@ -0,0 +1,44 @@
+"use client";
+
+import { useInfiniteQuery } from "@tanstack/react-query";
+import { fetchData } from "./actions";
+import { useMemo } from "react";
+import type {
+  MRT_SortingState,
+  MRT_ColumnFiltersState,
+} from "mantine-react-table";
+
+export function useAllData({
+  sorting,
+  columnFilters,
+}: {
+  sorting: MRT_SortingState;
+  columnFilters: MRT_ColumnFiltersState;
+}) {
+  // useInfiniteQuery is used to help with automatic pagination
+  const qr = useInfiniteQuery({
+    queryKey: ["all-__SCHEMA_NAME__", sorting, columnFilters],
+    queryFn: async ({ pageParam: offset }) => {
+      const result = await fetchData({ offset, sorting, columnFilters });
+      if (!result) throw new Error(`Failed to fetch __SCHEMA_NAME__`);
+      if (!result.data) throw new Error(`No data found for __SCHEMA_NAME__`);
+      return result?.data;
+    },
+    retry: false,
+    initialPageParam: 0,
+    getNextPageParam: (lastPage, pages) =>
+      lastPage.hasNextPage
+        ? pages.flatMap((page) => page.data).length
+        : undefined,
+  });
+
+  const flatData = useMemo(
+    () =>
+      qr.data?.pages.flatMap((page) => page.data).map((o) => o.fieldData) ?? [],
+    [qr.data]
+  );
+  const totalFetched = flatData.length;
+  const totalDBRowCount = qr.data?.pages?.[0]?.totalCount ?? 0;
+
+  return { ...qr, data: flatData, totalDBRowCount, totalFetched };
+}

package/template/pages/nextjs/table-infinite/table.tsx

@@ -0,0 +1,107 @@
+"use client";
+
+import { __TYPE_NAME__ } from "@/config/schemas/__SOURCE_NAME__/__SCHEMA_NAME__";
+import {
+  createMRTColumnHelper,
+  MantineReactTable,
+  MRT_ColumnDef,
+  MRT_ColumnFiltersState,
+  MRT_RowVirtualizer,
+  MRT_SortingState,
+  useMantineReactTable,
+} from "mantine-react-table";
+import React, {
+  type UIEvent,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { useAllData } from "./query";
+import { Text } from "@mantine/core";
+
+type TData = __TYPE_NAME__;
+
+const columns: MRT_ColumnDef<TData>[] = [];
+
+export default function MyTable() {
+  const tableContainerRef = useRef<HTMLDivElement>(null);
+  const rowVirtualizerInstanceRef =
+    useRef<MRT_RowVirtualizer<HTMLDivElement, HTMLTableRowElement>>(null);
+
+  const [sorting, setSorting] = useState<MRT_SortingState>([]);
+  const [columnFilters, setColumnFilters] = useState<MRT_ColumnFiltersState>(
+    []
+  );
+
+  const {
+    data,
+    totalDBRowCount,
+    totalFetched,
+    isLoading,
+    isFetching,
+    fetchNextPage,
+  } = useAllData({ sorting, columnFilters });
+
+  const table = useMantineReactTable({
+    data,
+    columns,
+    rowCount: totalDBRowCount,
+    enableRowVirtualization: true, // only render the rows that are visible on screen to improve performance
+    state: { isLoading, sorting, showProgressBars: isFetching, columnFilters },
+    enableGlobalFilter: false, // doesn't work as easily with server-side filters, it's better to filter the specific columns
+    onSortingChange: setSorting,
+    onColumnFiltersChange: setColumnFilters,
+    enablePagination: false, // hide pagination buttons
+    enableStickyHeader: true,
+    mantineBottomToolbarProps: { style: { alignItems: "center" } },
+    renderBottomToolbarCustomActions: () =>
+      !isLoading ? (
+        <Text px="sm">
+          Fetched {totalFetched} of {totalDBRowCount}
+        </Text>
+      ) : null,
+    mantineTableContainerProps: ({ table }) => {
+      return {
+        h: table.getState().isFullScreen
+          ? "100%"
+          : `calc(100vh - var(--app-shell-header-height) - 10rem)`, // may need to adjust this height if you have more elements on your page
+        ref: tableContainerRef,
+        onScroll: (
+          event: UIEvent<HTMLDivElement> //add an event listener to the table container element
+        ) => fetchMoreOnBottomReached(event.target as HTMLDivElement),
+      };
+    },
+  });
+
+  // called on scroll and possibly on mount to fetch more data as the user scrolls and reaches bottom of table
+  const fetchMoreOnBottomReached = useCallback(
+    (containerRefElement?: HTMLDivElement | null) => {
+      if (containerRefElement) {
+        const { scrollHeight, scrollTop, clientHeight } = containerRefElement;
+        // once the user has scrolled within 400px of the bottom of the table, fetch more data
+        if (
+          scrollHeight - scrollTop - clientHeight < 400 &&
+          !isFetching &&
+          totalFetched < totalDBRowCount
+        ) {
+          void fetchNextPage();
+        }
+      }
+    },
+    [fetchNextPage, isFetching, totalFetched, totalDBRowCount]
+  );
+
+  // scroll to top of table when sorting or filters change
+  useEffect(() => {
+    if (rowVirtualizerInstanceRef.current) {
+      try {
+        rowVirtualizerInstanceRef.current.scrollToIndex(0);
+      } catch (e) {
+        console.error(e);
+      }
+    }
+  }, [sorting, columnFilters]);
+
+  return <MantineReactTable table={table} />;
+}

package/template/pages/nextjs/table-infinite-edit/actions.ts

@@ -0,0 +1,84 @@
+"use server";
+
+import {
+  __TYPE_NAME__,
+  __ZOD_TYPE_NAME__,
+} from "@/config/schemas/__SOURCE_NAME__/__SCHEMA_NAME__";
+import { __CLIENT_NAME__ } from "@/config/schemas/__SOURCE_NAME__/client";
+import { __ACTION_CLIENT__ } from "@/server/safe-action";
+import { ListParams, Query } from "@proofkit/fmdapi/dist/client-types.js";
+import dayjs from "dayjs";
+import { z } from "zod/v4";
+
+import { idFieldName } from "./schema";
+
+const limit = 50; // raise or lower this number depending on how your layout performs
+export const fetchData = __ACTION_CLIENT__
+  .schema(
+    z.object({
+      offset: z.number().catch(0),
+      sorting: z.array(
+        z.object({ id: z.string(), desc: z.boolean().default(false) })
+      ),
+      columnFilters: z.array(z.object({ id: z.string(), value: z.unknown() })),
+    })
+  )
+  .action(async ({ parsedInput: { offset, sorting, columnFilters } }) => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const getOptions: ListParams<__TYPE_NAME__, any> & {
+      query: Query<__TYPE_NAME__>[];
+    } = {
+      limit,
+      offset,
+      query: [{ ["__FIRST_FIELD_NAME__"]: "*" }],
+    };
+
+    if (sorting.length > 0) {
+      getOptions.sort = sorting.map(({ id, desc }) => ({
+        fieldName: id as keyof __TYPE_NAME__,
+        sortOrder: desc ? "descend" : "ascend",
+      }));
+    }
+
+    if (columnFilters.length > 0) {
+      getOptions.query = columnFilters
+        .map(({ id, value }) => {
+          if (typeof value === "string") {
+            return {
+              [id]: value,
+            };
+          } else if (typeof value === "object" && value instanceof Date) {
+            return {
+              [id]: dayjs(value).format("YYYY+MM+DD"),
+            };
+          }
+          return null;
+        })
+        .filter(Boolean) as Query<any>[];
+    }
+
+    const data = await __CLIENT_NAME__.find(getOptions);
+
+    return {
+      data: data.data,
+      hasNextPage: data.dataInfo.foundCount > limit + offset,
+      totalCount: data.dataInfo.foundCount,
+    };
+  });
+
+export const updateRecord = __ACTION_CLIENT__
+  .schema(__ZOD_TYPE_NAME__.partial())
+  .action(async ({ parsedInput }) => {
+    const id = parsedInput[idFieldName];
+    delete parsedInput[idFieldName]; // this ensures the id field value is not included in the updated fieldData
+    const data = parsedInput;
+
+    const {
+      data: { recordId },
+    } = await __CLIENT_NAME__.findOne({ query: { [idFieldName]: `==${id}` } });
+
+    return await __CLIENT_NAME__.update({
+      recordId,
+      fieldData: data,
+    });
+  });

package/template/pages/nextjs/table-infinite-edit/page.tsx

@@ -0,0 +1,23 @@
+import { Stack, Text, Code } from "@mantine/core";
+import React from "react";
+
+import TableContent from "./table";
+import { idFieldName } from "./schema";
+
+export default async function TablePage() {
+  return (
+    <Stack>
+      <div>
+        <Text>
+          This table allows editing. Double-click on a cell to edit the value.
+        </Text>
+        <Text size="sm" c="dimmed">
+          NOTE: This feature requires a primary key field on your API layout. If your
+          primary key field is not <Code>{idFieldName}</Code>, update the
+          <Code>idFieldName</Code> variable in the <Code>schema.ts</Code> file.
+        </Text>
+      </div>
+      <TableContent  />
+    </Stack>
+  );
+}

package/template/pages/nextjs/table-infinite-edit/query.ts

@@ -0,0 +1,81 @@
+"use client";
+
+import { showErrorNotification } from "@/utils/notification-helpers";
+import {
+  useInfiniteQuery,
+  useMutation,
+  useQueryClient,
+} from "@tanstack/react-query";
+import type {
+  MRT_ColumnFiltersState,
+  MRT_SortingState,
+} from "mantine-react-table";
+import { useMemo } from "react";
+
+import { fetchData, updateRecord } from "./actions";
+import { idFieldName } from "./schema";
+
+export function useAllData({
+  sorting,
+  columnFilters,
+}: {
+  sorting: MRT_SortingState;
+  columnFilters: MRT_ColumnFiltersState;
+}) {
+  const queryKey = ["all-__SCHEMA_NAME__", sorting, columnFilters];
+  // useInfiniteQuery is used to help with automatic pagination
+  const qr = useInfiniteQuery({
+    queryKey,
+    queryFn: async ({ pageParam: offset }) => {
+      const result = await fetchData({ offset, sorting, columnFilters });
+      if (!result) throw new Error(`Failed to fetch __SCHEMA_NAME__`);
+      if (!result.data) throw new Error(`No data found for __SCHEMA_NAME__`);
+      return result?.data;
+    },
+    retry: false,
+    initialPageParam: 0,
+    getNextPageParam: (lastPage, pages) =>
+      lastPage.hasNextPage
+        ? pages.flatMap((page) => page.data).length
+        : undefined,
+  });
+
+  const flatData = useMemo(
+    () =>
+      qr.data?.pages.flatMap((page) => page.data).map((o) => o.fieldData) ?? [],
+    [qr.data]
+  );
+  const totalFetched = flatData.length;
+  const totalDBRowCount = qr.data?.pages?.[0]?.totalCount ?? 0;
+
+  const queryClient = useQueryClient();
+
+  const updateRecordMutation = useMutation({
+    mutationFn: updateRecord,
+    onMutate: async (newRecord) => {
+      // Cancel any outgoing refetches
+      await queryClient.cancelQueries({ queryKey });
+
+      // Optimistically update to the new value
+      queryClient.setQueryData<typeof qr.data>(queryKey, (old) => {
+        if (!old) return old;
+        return {
+          ...old,
+          pages: old.pages.map((page) => ({
+            ...page,
+            data: page.data.map((row) =>
+              row.fieldData[idFieldName] === newRecord[idFieldName]
+                ? { ...row, fieldData: { ...row.fieldData, ...newRecord } }
+                : row,
+            ),
+          })),
+        };
+      });
+    },
+    onError: () => {
+      showErrorNotification("Failed to update record");
+    },
+  });
+
+  return { ...qr, data: flatData, totalDBRowCount, totalFetched, updateRecord: updateRecordMutation.mutate };
+}

package/template/pages/nextjs/table-infinite-edit/schema.ts

@@ -0,0 +1,4 @@
+import { type __TYPE_NAME__ } from "@/config/schemas/__SOURCE_NAME__/__SCHEMA_NAME__";
+
+// TODO: Make sure this variable is properly set to your primary key field
+export const idFieldName: keyof __TYPE_NAME__ = "__FIRST_FIELD_NAME__";