@multiplatform.one/frappe-ui 6.0.0

package/src/FrappeTable.tsx

@@ -0,0 +1,402 @@
+import { FrappeApp, Order, useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
+import {
+  DataTable,
+  type DataTableColumn,
+  type DataTableProps,
+  type DataTableState,
+} from "@multiplatform.one/table";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { Spinner, Text, View, XStack, YStack } from "tamagui";
+import { FilterManager, SavedFilterDropdown, useSavedFilters } from "@multiplatform.one/table";
+import { useFrappeConfig } from "./FrappeProvider";
+
+/**
+ * Props for the FrappeTable component.
+ *
+ * @typeParam TDoc - The document type with at least name and doctype fields
+ */
+export interface FrappeTableProps<TDoc extends { name: string; doctype: string }> extends Omit<
+  DataTableProps<Partial<TDoc>>,
+  "data" | "columns"
+> {
+  /** Base URL for the Frappe server (uses FrappeProvider config if not set) */
+  baseURL?: string;
+  /** Authentication configuration */
+  auth?: {
+    /** Whether to use token authentication */
+    useToken?: boolean;
+    /** The authentication token */
+    token?: string;
+    /** Authentication type (e.g., 'token', 'cookie') */
+    type?: string;
+  };
+  /** Sync options for the live data subscription */
+  syncOptions?: any;
+  /** The Frappe DocType to display */
+  doctype: string;
+  /** Column definitions for the table */
+  columns: DataTableColumn<Partial<TDoc>>[];
+  /** Fields to fetch from the server */
+  fields?: readonly (keyof TDoc & string)[];
+  /** Initial filter criteria */
+  filters?: Partial<TDoc> | Array<[keyof TDoc & string, string, any]>;
+  /** Callback when a row is clicked */
+  onRowClick?: (row: Partial<TDoc>) => void;
+  /** Custom loading indicator */
+  loading?: React.ReactNode;
+  /** Custom error renderer */
+  error?: (error: Error) => React.ReactNode;
+  /** Enable saved filters feature */
+  savedFilters?: boolean;
+  /** Allow creating global (shared) filters */
+  canCreateGlobalFilters?: boolean;
+  /** Current user ID for saved filters */
+  userId?: string;
+  /**
+   * When true, enable server-side filtering, sorting, and pagination.
+   * Uses Frappe REST API (limit_start, limit_page_length, order_by, filters).
+   * Requires onStateChange for state sync; fetches data based on table state.
+   */
+  serverSide?: boolean;
+  /**
+   * Callback when filters, sort, or pagination change.
+   * Used for server-side fetches when serverSide is true.
+   */
+  onStateChange?: (state: DataTableState) => void;
+}
+
+/**
+ * A data table component connected to Frappe Live data.
+ *
+ * Displays documents from a Frappe DocType in a sortable, filterable table
+ * with real-time updates via WebSocket. Integrates with the FrappeProvider
+ * for configuration.
+ *
+ * @typeParam TDoc - The document type with at least name and doctype fields
+ *
+ * @example
+ * ```tsx
+ * interface ToDo {
+ *   name: string;
+ *   doctype: string;
+ *   description: string;
+ *   status: 'Open' | 'Closed';
+ * }
+ *
+ * function ToDoTable() {
+ *   return (
+ *     <FrappeProvider baseURL="https://mysite.frappe.cloud">
+ *       <FrappeTable<ToDo>
+ *         doctype="ToDo"
+ *         columns={[
+ *           { accessorKey: 'description', header: 'Description' },
+ *           { accessorKey: 'status', header: 'Status' }
+ *         ]}
+ *         fields={['name', 'description', 'status']}
+ *         onRowClick={(row) => console.log('Clicked:', row)}
+ *       />
+ *     </FrappeProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @category Components
+ */
+/** Map DataTable filter operator to Frappe filter operator */
+function mapFilterOperator(op: string): string {
+  const m: Record<string, string> = {
+    contains: "like",
+    doesNotContain: "not like",
+    is: "=",
+    isNot: "!=",
+    startsWith: "like",
+    endsWith: "like",
+    isEmpty: "=",
+    isNotEmpty: "!=",
+    isLessThan: "<",
+    isGreaterThan: ">",
+    isLessThanOrEqual: "<=",
+    isGreaterThanOrEqual: ">=",
+  };
+  return m[op] ?? "=";
+}
+
+/** Convert DataTableState to Frappe API params */
+function stateToFrappeParams(state: DataTableState) {
+  const { pagination, sorting, filters, columnFilters, globalFilter } = state;
+  const limitStart = pagination.pageIndex * pagination.pageSize;
+  const limit = pagination.pageSize;
+
+  const frappeFilters: Array<[string, string, unknown]> = [];
+  if (filters?.length) {
+    for (const f of filters) {
+      const op = mapFilterOperator(f.value?.operator ?? "is");
+      const val = f.value?.value;
+      if (op === "like" && typeof val === "string" && !val.includes("%")) {
+        frappeFilters.push([f.columnId, op, `%${val}%`]);
+      } else {
+        frappeFilters.push([f.columnId, op, val]);
+      }
+    }
+  }
+  for (const cf of columnFilters ?? []) {
+    if (cf.value != null && cf.value !== "") {
+      frappeFilters.push([cf.id, "=", cf.value]);
+    }
+  }
+  if (globalFilter && typeof globalFilter === "string" && globalFilter.trim()) {
+    frappeFilters.push(["name", "like", `%${globalFilter}%`]);
+  }
+
+  const orderBy =
+    sorting?.length && sorting[0]
+      ? sorting.map((s) => ({ field: s.id, order: s.desc ? Order.Desc : Order.Asc }))
+      : undefined;
+
+  return { limitStart, limit, filters: frappeFilters, orderBy };
+}
+
+export function FrappeTable<TDoc extends { name: string; doctype: string }>({
+  baseURL,
+  auth,
+  syncOptions,
+  doctype,
+  columns,
+  fields,
+  filters: initialFilters,
+  onRowClick,
+  loading,
+  error,
+  savedFilters = false,
+  canCreateGlobalFilters = false,
+  userId,
+  serverSide = false,
+  onStateChange: onStateChangeProp,
+  ...dataTableProps
+}: FrappeTableProps<TDoc>) {
+  const { knobProps } = useResolvedKnobs();
+  const { t } = useTranslation();
+  const [errorState, setErrorState] = React.useState<Error | null>(null);
+  const [activeFilters, setActiveFilters] = React.useState<
+    Partial<TDoc> | Array<[keyof TDoc & string, string, any]> | undefined
+  >(initialFilters);
+  const config = useFrappeConfig();
+
+  const finalBaseURL = baseURL ?? config?.baseURL;
+  const finalAuth = auth ?? config?.auth;
+  const finalSyncOptions = syncOptions ?? config?.syncOptions;
+
+  if (!finalBaseURL) {
+    throw new Error("FrappeTable requires baseURL prop or FrappeProvider with baseURL");
+  }
+
+  const frappeApp = useMemo(() => {
+    if (!serverSide || !finalBaseURL) return null;
+    return new FrappeApp(finalBaseURL, (finalAuth ?? {}) as Record<string, unknown>);
+  }, [serverSide, finalBaseURL, finalAuth]);
+
+  const [serverData, setServerData] = useState<TDoc[]>([]);
+  const [serverRowCount, setServerRowCount] = useState(0);
+  const [serverLoading, setServerLoading] = useState(serverSide);
+  const lastFetchKey = useRef<string>("");
+
+  const fetchServerData = useCallback(
+    async (state: DataTableState) => {
+      if (!frappeApp || !serverSide) return;
+      const params = stateToFrappeParams(state);
+      const key = JSON.stringify(params);
+      if (key === lastFetchKey.current) return;
+      lastFetchKey.current = key;
+      setServerLoading(true);
+      try {
+        const [data, count] = await Promise.all([
+          frappeApp.db().getDocList<TDoc>(doctype, {
+            fields: (fields as string[]) ?? ["name"],
+            filters: params.filters.length ? params.filters : undefined,
+            limitStart: params.limitStart,
+            limit: params.limit,
+            orderBy: params.orderBy,
+          }),
+          frappeApp.db().getCount(doctype, params.filters.length ? params.filters : undefined),
+        ]);
+        setServerData(data);
+        setServerRowCount(count);
+        setErrorState(null);
+      } catch (err) {
+        setErrorState(err instanceof Error ? err : new Error(String(err)));
+        setServerData([]);
+        setServerRowCount(0);
+      } finally {
+        setServerLoading(false);
+      }
+    },
+    [frappeApp, serverSide, doctype, fields],
+  );
+
+  const handleStateChange = useCallback(
+    (state: DataTableState) => {
+      onStateChangeProp?.(state);
+      if (serverSide) fetchServerData(state);
+    },
+    [onStateChangeProp, serverSide, fetchServerData],
+  );
+
+  useEffect(() => {
+    if (serverSide && frappeApp) {
+      lastFetchKey.current = "";
+      fetchServerData({
+        data: [],
+        columns: columns as any,
+        pagination: { pageIndex: 0, pageSize: 10 },
+        sorting: [],
+        filters: [],
+        columnFilters: [],
+        columnVisibility: {},
+        columnOrder: columns.map((c) => c.id ?? ""),
+        columnSizing: {},
+      } as DataTableState);
+    }
+  }, [serverSide, !!frappeApp, fetchServerData]);
+
+  const savedFiltersHook = savedFilters ? useSavedFilters({ userId }) : null;
+
+  const collection = useFrappeCollection<TDoc>(
+    serverSide
+      ? undefined
+      : {
+          baseURL: finalBaseURL,
+          socketPort: config?.socketPort,
+          auth: finalAuth,
+          syncOptions: finalSyncOptions,
+          fixtures: config?.fixtures,
+        },
+    serverSide ? "" : doctype,
+    serverSide ? undefined : { fields, filters: activeFilters },
+  );
+  const { data: rawData, isLoading: isRowsLoading } = useLiveQuery(
+    (q) => (collection ? q.from({ _list: collection }) : null),
+    [collection],
+  );
+  const clientRows = useMemo(() => (rawData as TDoc[] | undefined) ?? [], [rawData]);
+
+  const rows = serverSide ? serverData : clientRows;
+  const isRowsLoadingResolved = serverSide ? serverLoading : isRowsLoading;
+
+  const handleSelectFilter = (filter: any) => {
+    if (filter) {
+      setActiveFilters(filter.filters);
+    } else {
+      setActiveFilters(initialFilters);
+    }
+  };
+
+  const handleSaveFilter = async (filterName: string, isGlobal: boolean) => {
+    if (!savedFiltersHook || !activeFilters) return;
+    const filterArray = Array.isArray(activeFilters)
+      ? activeFilters
+      : Object.entries(activeFilters).map(
+          ([key, value]) => [key, "=", value] as [string, string, any],
+        );
+    await savedFiltersHook.saveFilter(filterName, filterArray, isGlobal);
+  };
+
+  const handleDeleteFilter = async (name: string) => {
+    if (!savedFiltersHook) return;
+    await savedFiltersHook.deleteFilter(name);
+  };
+
+  if (errorState && error) {
+    return <>{error(errorState)}</>;
+  }
+
+  if (errorState) {
+    return (
+      <YStack {...knobProps.panelPadding} alignItems="center">
+        <Text color="$red10">{t("Error loading {{doctype}}", { doctype })}</Text>
+        <Text color="$color10" fontSize="$2">
+          {errorState.message}
+        </Text>
+      </YStack>
+    );
+  }
+
+  if (isRowsLoadingResolved) {
+    if (loading) {
+      return <>{loading}</>;
+    }
+    return (
+      <YStack {...knobProps.panelPadding} alignItems="center">
+        <Spinner size="large" />
+        <Text color="$color10" marginTop="$2">
+          {t("Loading {{doctype}}...", { doctype })}
+        </Text>
+      </YStack>
+    );
+  }
+
+  const rowData = rows ?? [];
+  if (rowData.length === 0) {
+    return (
+      <YStack {...knobProps.panelPadding} alignItems="center">
+        <Text color="$color10">{t("No {{doctype}} records found", { doctype })}</Text>
+      </YStack>
+    );
+  }
+
+  const columnsWithClick: DataTableColumn<Partial<TDoc>>[] = onRowClick
+    ? columns.map((col) => ({
+        ...col,
+        cell: (props) => (
+          <View
+            onPress={() => onRowClick(props.row.original)}
+            cursor="pointer"
+            hoverStyle={{ backgroundColor: "$color2" }}
+          >
+            {typeof col.cell === "function" ? col.cell(props) : props.getValue()}
+          </View>
+        ),
+      }))
+    : columns;
+
+  return (
+    <YStack {...knobProps.gap} flex={1}>
+      {savedFilters && savedFiltersHook && (
+        <XStack {...knobProps.gap} padding="$2">
+          <SavedFilterDropdown
+            filters={savedFiltersHook.filters}
+            selectedFilter={null}
+            onSelectFilter={handleSelectFilter}
+            onDeleteFilter={handleDeleteFilter}
+          />
+          <FilterManager
+            currentFilters={
+              Array.isArray(activeFilters)
+                ? activeFilters
+                : activeFilters
+                  ? Object.entries(activeFilters).map(
+                      ([key, value]) => [key, "=", value] as [string, string, any],
+                    )
+                  : []
+            }
+            onSaveFilter={handleSaveFilter}
+            canCreateGlobal={canCreateGlobalFilters}
+          />
+        </XStack>
+      )}
+      <DataTable
+        data={rowData}
+        columns={columnsWithClick}
+        {...(serverSide && {
+          manualFiltering: true,
+          manualPagination: true,
+          manualSorting: true,
+          rowCount: serverRowCount,
+          onStateChange: handleStateChange,
+        })}
+        {...dataTableProps}
+      />
+    </YStack>
+  );
+}