@tulip-systems/core 0.2.0

package/src/modules/data-tables/lib/converters/sorting.ts

@@ -0,0 +1,25 @@
+import { asc, desc, type AnyColumn, type SQL, type ValueOrArray } from "drizzle-orm";
+import type { PgColumn, PgTable } from "drizzle-orm/pg-core";
+import { TableQuerySchema } from "../validators";
+
+export type ConvertSortToQueryParamsFallback = ValueOrArray<AnyColumn | SQL>;
+
+/**
+ * Convert pagination to DB query
+ * @param {ConvertSortToQueryParamsInput} pagination
+ * @returns { { orderBy: Record<string, "asc" | "desc"> } }
+ */
+export function convertOrderByToQueryParams(
+  query: Pick<TableQuerySchema, "sort" | "order">,
+  table: PgTable,
+  fallback: ConvertSortToQueryParamsFallback,
+): ValueOrArray<AnyColumn | SQL> {
+  const { sort, order } = query;
+
+  if (sort && sort in table) {
+    const column = table[sort as keyof typeof table] as PgColumn;
+    return order === "asc" ? asc(column) : desc(column);
+  }
+
+  return fallback;
+}

package/src/modules/data-tables/lib/filters/config.ts

@@ -0,0 +1,6 @@
+import { ZodType } from "zod";
+import { ParseFilter } from "./parsers";
+
+export type TableFiltersDef = { readonly [k: string]: ParseFilter<ZodType> };
+
+export const createTableFilters = <TDef extends TableFiltersDef>(def: TDef) => def;

package/src/modules/data-tables/lib/filters/parsers.ts

@@ -0,0 +1,66 @@
+import z, { ZodEnum, ZodNullable, ZodType } from "zod";
+
+export type ParseFilter<TSchema extends z.ZodType> = {
+  schema: ZodNullable<TSchema>;
+  decode: (value: string) => z.input<TSchema>;
+  encode: (value: z.input<TSchema>) => string;
+  eq?: (a: z.output<TSchema>, b: z.output<TSchema>) => boolean;
+};
+
+/**
+ * Filter uuid array
+ */
+export type ParseFilterArraySchema = z.ZodArray<ZodType>;
+
+export const parseFilterArray = <TSchema extends ParseFilterArraySchema>(
+  schema: TSchema,
+): ParseFilter<TSchema> => ({
+  schema: schema.nullable(),
+  decode: (encoded) => (encoded?.split(",").filter(Boolean) ?? []) as unknown as z.input<TSchema>,
+  encode: (decoded) => decoded?.join(",") ?? "",
+});
+
+/**
+ * Filter enum
+ */
+export type ParseFilterEnumSchema = ZodEnum;
+
+export const parseFilterEnum = <TSchema extends ZodEnum>(
+  schema: TSchema,
+): ParseFilter<TSchema> => ({
+  schema: schema.nullable(),
+  decode: (encoded) => {
+    const value = encoded?.trim().toLowerCase();
+    return value as unknown as z.input<TSchema>;
+  },
+  encode: (decoded) => decoded as unknown as string,
+});
+
+/**
+ * Filter boolean value
+ */
+export type ParseFilterBooleanSchema = z.ZodBoolean;
+
+export const parseFilterBoolean = <TSchema extends z.ZodType<boolean>>(
+  schema: TSchema,
+): ParseFilter<TSchema> => ({
+  schema: schema.nullable(),
+  decode: (encoded) => {
+    const value = encoded?.trim().toLowerCase();
+    return (value === "true") as unknown as z.input<TSchema>;
+  },
+  encode: (decoded) => (decoded ? "true" : "false"),
+});
+
+/**
+ * Filter range value
+ */
+export type ParseFilterTupleSchema = z.ZodTuple<[ZodType, ZodType]>;
+
+export const parseFilterTuple = <TSchema extends ParseFilterTupleSchema>(
+  schema: TSchema,
+): ParseFilter<TSchema> => ({
+  schema: schema.nullable(),
+  decode: (encoded) => (encoded?.split("_") ?? []) as unknown as z.input<TSchema>,
+  encode: (decoded) => decoded?.join("_") ?? "",
+});

package/src/modules/data-tables/lib/filters/resolvers.ts

@@ -0,0 +1,61 @@
+import { createParser } from "nuqs/server";
+import z from "zod";
+import { TableFiltersDef } from "./config";
+
+/**
+ * Resolvers for nuqs search params
+ */
+export function resolveFiltersSearchParams<TDef extends TableFiltersDef>(def: TDef) {
+  const entries = typedEntries(def).map(([key, value]) => {
+    const codec = z.codec(z.string(), value.schema, { decode: value.decode, encode: value.encode });
+    const parser = createParser<z.output<typeof value.schema>>({
+      parse: (query) => codec.parse(query),
+      serialize: (value) => codec.encode(value),
+      eq: value.eq,
+    });
+
+    return [key, parser] as const;
+  });
+
+  return typedFromEntries(entries) as {
+    readonly [K in keyof TDef]: ReturnType<typeof createParser<z.output<TDef[K]["schema"]>>>;
+  };
+}
+
+/**
+ * Resolvers for zod schema
+ */
+export function resolveFiltersSchema<TDef extends TableFiltersDef>(def: TDef) {
+  const entries = typedEntries(def).map(([k, f]) => [k, f.schema] as const);
+  const shape = typedFromEntries(entries) as { [K in keyof TDef]: TDef[K]["schema"] };
+
+  return z.object(shape);
+}
+
+/**
+ * Resolvers for filter descriptors
+ */
+export function resolveFilterDescriptors<TDef extends TableFiltersDef>(def: TDef) {
+  const params = resolveFiltersSearchParams(def);
+  const entries = typedEntries(params).map(
+    ([key, parser]) => [key, { name: key, parser }] as const,
+  );
+
+  return typedFromEntries(entries) as {
+    [K in keyof typeof params]: { name: K; parser: (typeof params)[K] };
+  };
+}
+
+/**
+ * Helpers
+ */
+function typedEntries<T extends { [K in PropertyKey]: unknown }>(obj: T) {
+  return Object.entries(obj) as { [K in keyof T]: [K, T[K]] }[keyof T][];
+}
+
+function typedFromEntries<K extends PropertyKey, V>(
+  entries: Iterable<readonly [K, V]>,
+): { [P in K]: V } {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return Object.fromEntries(entries as any) as any;
+}

package/src/modules/data-tables/lib/helpers/create-column.ts

@@ -0,0 +1,9 @@
+import { TableColumnDef } from "../types";
+
+export function createTableCell(column: TableColumnDef<unknown>) {
+  return <TData>(newColumn?: Partial<TableColumnDef<TData>>): TableColumnDef<TData> =>
+    ({
+      ...column,
+      ...newColumn,
+    }) as TableColumnDef<TData>;
+}

package/src/modules/data-tables/lib/search-params.ts

@@ -0,0 +1,12 @@
+import { parseAsIndex, parseAsInteger, parseAsString, parseAsStringLiteral } from "nuqs";
+
+/**
+ * Searchparams
+ */
+export const tableSearchParams = {
+  cursor: parseAsIndex.withDefault(0),
+  limit: parseAsInteger.withDefault(20),
+  sort: parseAsString,
+  order: parseAsStringLiteral(["asc", "desc"]),
+  search: parseAsString,
+};

package/src/modules/data-tables/lib/types.ts

@@ -0,0 +1,63 @@
+import { Permission } from "@/modules/auth/lib/permissions";
+import { CommandDef } from "@/modules/commands/lib/definitions";
+import type { RowSelectionState, Updater } from "@tanstack/react-table";
+import { ColumnDef, PaginationState, SortingState } from "@tanstack/react-table";
+import { UseQueryStatesKeysMap } from "nuqs";
+
+/**
+ * Data table meta
+ */
+export type TableMeta<TData extends { id: string }> = {
+  strategy: TableStrategy;
+  selectedData: TData[];
+  commands?: CommandDef<TData>[];
+};
+
+/**
+ * Table column definition
+ */
+export type TableColumnDef<TData> = ColumnDef<TData> & {
+  permissions?: Permission;
+  meta?: TableColumnMeta;
+};
+
+/**
+ * Data table strategy
+ */
+export type TableStrategy = {
+  name: "pagination" | "infinite";
+  // Pagination
+  rowCount?: number;
+  paginationState?: PaginationState;
+  manualPagination?: boolean;
+  onPaginationChange?: (updater: Updater<PaginationState>) => PaginationState;
+
+  resetCursor: () => number | null;
+  tableSearchParams: UseQueryStatesKeysMap;
+
+  // Sorting
+  sortingState: SortingState;
+  manualSorting: boolean;
+  onSortingChange: (updater: Updater<SortingState>) => SortingState;
+
+  // Meta
+  meta?: object;
+};
+
+/**
+ * Data table meta
+ */
+export type TableColumnMeta = object;
+
+/**
+ * Data table selection
+ */
+export type Selection =
+  | {
+      rowSelection: RowSelectionState;
+      setRowSelection: (row: Updater<RowSelectionState>) => void;
+    }
+  | {
+      rowSelection?: undefined;
+      setRowSelection?: undefined;
+    };

package/src/modules/data-tables/lib/validators.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+/**
+ * Server data table query schema
+ */
+export const tableQuerySchema = z.object({
+  cursor: z.coerce
+    .number()
+    .optional()
+    .default(0)
+    .transform((val) => Math.max(val, 0)),
+  limit: z.coerce
+    .number()
+    .optional()
+    .default(10)
+    .transform((val) => Math.min(Math.max(val, 1), 1000)),
+  sort: z.string().nullable().optional(),
+  order: z.enum(["asc", "desc"]).nullable().optional(),
+  search: z.string().nullable().optional(),
+});
+
+export type TableQuerySchema = z.infer<typeof tableQuerySchema>;

package/src/modules/data-tables/server/get-data.server.ts

@@ -0,0 +1,78 @@
+import "server-only";
+
+import { type TDatabaseSchema } from "@/modules/config/db/types";
+import { GetTulipReturn } from "@/modules/config/lib/resolve.server";
+import { and, getTableName, isTable, type DBQueryConfig, type SQL } from "drizzle-orm";
+import { type PgTable } from "drizzle-orm/pg-core";
+import type { RelationalQueryBuilder } from "drizzle-orm/pg-core/query-builders/query";
+import { convertCursorToQueryParams } from "../lib/converters/cursor";
+import { ConvertSearchToQueryParamsFields, convertSearchToQueryParams } from "../lib/converters/search";
+import { ConvertSortToQueryParamsFallback, convertOrderByToQueryParams } from "../lib/converters/sorting";
+import { TableQuerySchema } from "../lib/validators";
+
+export type GetTableDataOptions<TTable extends PgTable> = DBQueryConfig<"many"> & {
+  table: TTable;
+  where?: SQL;
+  columns?: keyof TTable["_"]["columns"];
+  defaultOrder: ConvertSortToQueryParamsFallback;
+  searchFields: ConvertSearchToQueryParamsFields;
+};
+
+/**
+ * Get data from the database for the data table
+ */
+export async function getTableData<TTable extends PgTable, TSchema extends TDatabaseSchema>(
+  { db, schema }: GetTulipReturn<TSchema>,
+  query: TableQuerySchema,
+  options: GetTableDataOptions<TTable>,
+): Promise<{ data: TTable["$inferSelect"][]; total: number }> {
+  const { table, where, defaultOrder: defaultSort, searchFields } = options;
+
+  if (!isTable(table)) throw new Error(`Provided table is not a table: ${table}`);
+
+  // Get the table name kay from the schema
+  const tableName = Object.entries({ ...schema } as { [key: string]: PgTable })
+    .filter(([, t]) => isTable(t))
+    .find(([, t]) => getTableName(t) === getTableName(table))?.[0];
+
+  if (!tableName) throw new Error(`Table name not found for table: ${tableName}`);
+
+  // Convert the query params to DB query
+  const { limit, offset } = convertCursorToQueryParams(query);
+  const orderBy = convertOrderByToQueryParams(query, table, defaultSort);
+  const search = convertSearchToQueryParams(query, searchFields);
+
+  /**
+   * Make a transaction to get the data
+   */
+  const { data, total } = await db.transaction(async (tx) => {
+    // Check if the table exists in the query builder
+    if (!(tableName in tx.query)) throw new Error(`Table not found in query builder: ${tableName}`);
+    const queryBuilderKey = tableName as keyof typeof tx.query;
+
+    // Get the query builder
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const queryBuilder = tx.query[queryBuilderKey] as RelationalQueryBuilder<any, any>;
+    if (!queryBuilder) throw new Error(`Query builder not found for table: ${tableName}`);
+
+    // Get the data
+    const data = await queryBuilder.findMany({
+      where: and(where, search),
+      orderBy,
+      limit,
+      offset,
+      with: options.with,
+      columns: options.columns,
+      extras: options.extras,
+    });
+
+    // Get the total
+    // Get the total
+    const total = await tx.$count(table, and(where, search));
+
+    // Return the data
+    return { data, total: total ?? 0 };
+  });
+
+  return { data, total };
+}

package/src/modules/data-tables/strategies/helpers/sorting.ts

@@ -0,0 +1,65 @@
+import type { SortingState, Updater } from "@tanstack/react-table";
+import { parseAsString, parseAsStringLiteral, SetValues } from "nuqs";
+import { z } from "zod";
+
+/**
+ * Sorting schema
+ */
+export const sortingSchema = z.object({
+  sort: z.string().nullable().optional(),
+  order: z.enum(["asc", "desc"]).nullable().optional(),
+});
+
+export type Sorting = z.infer<typeof sortingSchema>;
+
+/**
+ * Search params
+ */
+export const sortingSearchParams = {
+  sort: parseAsString,
+  order: parseAsStringLiteral(["asc", "desc"] as const),
+};
+
+/**
+ * Convert sorting to table state
+ * @param {Sorting} sorting
+ * @returns { SortingState }
+ */
+export function convertSortingToTableState(sorting: Sorting): SortingState {
+  const { sort, order } = sorting;
+  return sort ? [{ id: sort, desc: order === "desc" }] : [];
+}
+
+/**
+ * Handle sorting change
+ */
+type HandleSortingChangeProps = {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  setQuery: SetValues<{}>;
+  sortingState: SortingState;
+  resetCursor: () => number | null;
+};
+
+export function handleSortingChange({
+  sortingState,
+  setQuery,
+  resetCursor,
+}: HandleSortingChangeProps) {
+  return (updater: Updater<SortingState>): SortingState => {
+    // Get the new state from the updater function
+    const newState = typeof updater === "function" ? updater(sortingState) : updater;
+
+    // Update the search params
+    const { id, desc } = newState[0] ?? { id: null, desc: null };
+
+    const cursor = resetCursor();
+    setQuery({
+      sort: id?.replaceAll("_", ".") ?? null,
+      order: desc === null ? null : desc ? "desc" : "asc",
+      cursor,
+    });
+
+    // Return the new state
+    return newState;
+  };
+}

package/src/modules/data-tables/strategies/infinite/components.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+import { Skeleton } from "@/components/ui/skeleton";
+import { Table } from "@tanstack/react-table";
+import { useInView } from "motion/react";
+import { useEffect, useRef } from "react";
+import { TableCell, TableRow } from "../../components/table";
+import { TableMeta } from "../../lib/types";
+import { InfiniteStrategyMeta } from "./strategy";
+
+/**
+ * Infinite table bottombar
+ */
+export function InfinteTableBottombar<TData extends { id: string }>({
+  table,
+}: {
+  table: Table<TData>;
+}) {
+  const scrollRef = useRef(null);
+  const isInView = useInView(scrollRef);
+
+  const hasNextPage = table.getCanNextPage();
+  const fetchNextPage = table.nextPage;
+
+  const meta = table.options.meta as TableMeta<TData>;
+  const { isFetching, isFetchingNextPage } = meta.strategy.meta as InfiniteStrategyMeta;
+
+  useEffect(() => {
+    if (isInView && hasNextPage && !isFetching && !isFetchingNextPage) {
+      fetchNextPage();
+    }
+  }, [isInView, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage]);
+
+  return (
+    <div className="relative">
+      <div ref={scrollRef} className="absolute bottom-0 -z-50 min-h-[500px]" />
+    </div>
+  );
+}
+
+/**
+ * Infinite table footer
+ */
+export function InfinteTableFooter<TData extends { id: string }>({
+  table,
+}: {
+  table: Table<TData>;
+}) {
+  const meta = table.options.meta as TableMeta<TData>;
+  const { isFetchingNextPage } = meta.strategy.meta as InfiniteStrategyMeta;
+
+  const pageSize = table.getState().pagination.pageSize;
+  const columnLength = table.getAllFlatColumns().length;
+
+  return (
+    isFetchingNextPage &&
+    Array.from({ length: pageSize }).map((_, index) => (
+      <TableRow key={index} className="relative">
+        {Array.from({ length: columnLength }).map((_, index) => (
+          <TableCell key={index}>
+            <Skeleton className="my-2 h-2 w-full rounded-full" />
+          </TableCell>
+        ))}
+      </TableRow>
+    ))
+  );
+}

package/src/modules/data-tables/strategies/infinite/strategy.ts

@@ -0,0 +1,70 @@
+"use client";
+
+import { PaginationState, Updater } from "@tanstack/react-table";
+import { useQueryStates } from "nuqs";
+import { tableSearchParams } from "../../entry";
+import { TableStrategy } from "../../lib/types";
+import { handleSortingChange } from "../helpers/sorting";
+
+export interface UseInfiniteStrategyInput {
+  cursor: number | undefined;
+  total: number | undefined;
+  fetchNextPage: () => void;
+  isFetching: boolean;
+  isFetchingNextPage: boolean;
+}
+
+export type InfiniteStrategyMeta = Pick<
+  UseInfiniteStrategyInput,
+  "isFetching" | "isFetchingNextPage"
+>;
+
+export function useInfiniteStrategy({
+  cursor,
+  total,
+  fetchNextPage,
+  isFetching,
+  isFetchingNextPage,
+}: UseInfiniteStrategyInput): TableStrategy {
+  const [query, setQuery] = useQueryStates(tableSearchParams);
+
+  // Convert pagination to table state
+  const paginationState = {
+    pageIndex: cursor ?? 0,
+    pageSize: query.limit,
+  };
+
+  // Convert sorting to table state
+  const sortingState = query.sort ? [{ id: query.sort, desc: query.order === "desc" }] : [];
+
+  const resetCursor = () => null;
+
+  return {
+    name: "infinite",
+    rowCount: total,
+    paginationState,
+    manualPagination: true,
+    onPaginationChange: (updater: Updater<PaginationState>) => {
+      // Get the new state from the updater function
+      const newState = typeof updater === "function" ? updater(paginationState) : updater;
+
+      // Update the search params
+      setQuery({ limit: newState.pageSize });
+
+      // Fetch the next page
+      fetchNextPage();
+
+      // Return the new state
+      return newState;
+    },
+    resetCursor,
+    tableSearchParams: tableSearchParams,
+    sortingState,
+    manualSorting: true,
+    onSortingChange: handleSortingChange({ sortingState, setQuery, resetCursor }),
+    meta: {
+      isFetching,
+      isFetchingNextPage,
+    } satisfies InfiniteStrategyMeta,
+  };
+}

package/src/modules/data-tables/strategies/pagination/components.tsx

@@ -0,0 +1,117 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select.client";
+import { Table } from "@tanstack/react-table";
+import { ChevronLeft, ChevronRight, ChevronsLeft, ChevronsRight, XIcon } from "lucide-react";
+
+export function PaginationTableFooter<TData extends { id: string }>({
+  table,
+}: {
+  table: Table<TData>;
+}) {
+  const selected = Object.keys(table.getState().rowSelection).length;
+  const total = table.getRowCount();
+
+  return (
+    <div className="flex flex-col gap-y-4 px-2 md:flex-row md:items-center md:justify-between">
+      <div className="flex items-center gap-2">
+        {selected > 0 && (
+          <Button
+            type="button"
+            size="icon"
+            variant="ghost"
+            className="h-4 w-4 rounded-full"
+            onClick={() => table.resetRowSelection()}
+          >
+            <XIcon className="h-2 w-2" />
+          </Button>
+        )}
+
+        <div className="text-muted-foreground flex-1 text-sm">
+          {selected ?? table.getFilteredSelectedRowModel().rows.length} of{" "}
+          {total ?? table.getFilteredRowModel().rows.length} row(s) selected.
+        </div>
+      </div>
+
+      <div className="flex items-center justify-between gap-x-6 md:justify-start lg:space-x-8">
+        <div className="hidden items-center space-x-2 md:flex">
+          <p className="text-sm font-medium">Rows per page</p>
+          <Select
+            value={`${table.getState().pagination.pageSize}`}
+            onValueChange={(value) => {
+              table.setPageSize(Number(value));
+            }}
+          >
+            <SelectTrigger className="h-8 w-[70px]">
+              <SelectValue placeholder={table.getState().pagination.pageSize} />
+            </SelectTrigger>
+            <SelectContent side="top">
+              {[10, 20, 30, 40, 50, 100, 300, 500].map((pageSize) => (
+                <SelectItem key={pageSize} value={`${pageSize}`}>
+                  {pageSize}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+
+        <div className="flex items-center justify-center text-sm font-medium">
+          Page {table.getState().pagination.pageIndex + 1} of {table.getPageCount()}
+        </div>
+
+        <div className="flex items-center space-x-2">
+          <Button
+            type="button"
+            variant="outline"
+            className="hidden h-8 w-8 p-0 lg:flex"
+            onClick={() => table.setPageIndex(0)}
+            disabled={!table.getCanPreviousPage()}
+          >
+            <span className="sr-only">Go to first page</span>
+            <ChevronsLeft className="h-4 w-4" />
+          </Button>
+
+          <Button
+            type="button"
+            variant="outline"
+            className="h-8 w-8 p-0"
+            onClick={() => table.previousPage()}
+            disabled={!table.getCanPreviousPage()}
+          >
+            <span className="sr-only">Go to previous page</span>
+            <ChevronLeft className="h-4 w-4" />
+          </Button>
+
+          <Button
+            type="button"
+            variant="outline"
+            className="h-8 w-8 p-0"
+            onClick={() => table.nextPage()}
+            disabled={!table.getCanNextPage()}
+          >
+            <span className="sr-only">Go to next page</span>
+            <ChevronRight className="h-4 w-4" />
+          </Button>
+
+          <Button
+            type="button"
+            variant="outline"
+            className="hidden h-8 w-8 p-0 lg:flex"
+            onClick={() => table.setPageIndex(table.getPageCount() - 1)}
+            disabled={!table.getCanNextPage()}
+          >
+            <span className="sr-only">Go to last page</span>
+            <ChevronsRight className="h-4 w-4" />
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}