@multiplatform.one/frappe-ui 6.0.0

package/src/FrappeReportBuilder.tsx

@@ -0,0 +1,405 @@
+import { useDocTypeMeta, useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
+import { downloadBlob } from "@multiplatform.one/platform";
+import {
+  ReportBuilder,
+  type ReportColumn,
+  type GroupByConfig,
+} from "@multiplatform.one/components";
+import { storage } from "@multiplatform.one/store";
+import React, { useMemo, useState, useCallback, useEffect } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  Button,
+  Popover,
+  Separator,
+  Spinner,
+  Text,
+  XStack,
+  YStack,
+  type YStackProps,
+  Input,
+} from "tamagui";
+import { FloppyDiskIcon, FolderOpenIcon, TrashIcon } from "@phosphor-icons/react";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useFrappeConfig } from "./FrappeProvider";
+
+// ============================================================================
+// Saved Report Types (Frappe-specific persisted storage)
+// ============================================================================
+
+interface SavedReport {
+  name: string;
+  columns: string[];
+  groupBy: GroupByConfig | null;
+  filters: Record<string, unknown> | Array<[string, string, unknown]> | undefined;
+}
+
+function getSavedReportsKey(doctype: string) {
+  return `frappe-report-${doctype}`;
+}
+
+async function loadSavedReports(doctype: string): Promise<SavedReport[]> {
+  try {
+    const raw = await Promise.resolve(storage.getItem(getSavedReportsKey(doctype)));
+    if (raw) return JSON.parse(raw) as SavedReport[];
+  } catch {
+    // storage not available
+  }
+  return [];
+}
+
+async function persistSavedReports(doctype: string, reports: SavedReport[]): Promise<void> {
+  try {
+    await Promise.resolve(storage.setItem(getSavedReportsKey(doctype), JSON.stringify(reports)));
+  } catch {
+    // storage not available
+  }
+}
+
+// ============================================================================
+// Props
+// ============================================================================
+
+export interface FrappeReportBuilderProps extends Omit<YStackProps, "children"> {
+  doctype: string;
+  initialColumns?: ReportColumn[];
+  initialGroupBy?: GroupByConfig;
+  filters?: Record<string, unknown> | Array<[string, string, unknown]>;
+  showChart?: boolean;
+  onExport?: (data: Record<string, unknown>[]) => void;
+  baseURL?: string;
+  auth?: { useToken?: boolean; token?: string; type?: string };
+  syncOptions?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * Thin Frappe wrapper around the generic ReportBuilder component.
+ *
+ * Fetches DocType metadata and data via Frappe hooks, then passes
+ * column definitions and data to the generic `ReportBuilder` from
+ * `@multiplatform.one/components`. Adds Frappe-specific features:
+ * save/load reports to shared storage, CSV export.
+ */
+export function FrappeReportBuilder({
+  doctype,
+  initialColumns,
+  initialGroupBy,
+  filters,
+  showChart = false,
+  onExport,
+  baseURL,
+  auth,
+  syncOptions,
+  ...stackProps
+}: FrappeReportBuilderProps) {
+  const config = useFrappeConfig();
+  const { knobProps } = useResolvedKnobs();
+  const { t } = useTranslation();
+
+  const finalBaseURL = baseURL ?? config?.baseURL;
+  const finalAuth = auth ?? config?.auth;
+  const finalSyncOptions = syncOptions ?? config?.syncOptions;
+
+  if (!finalBaseURL) {
+    throw new Error("FrappeReportBuilder requires baseURL prop or FrappeProvider with baseURL");
+  }
+
+  const connectionConfig = {
+    baseURL: finalBaseURL,
+    socketPort: config?.socketPort,
+    auth: finalAuth,
+    syncOptions: finalSyncOptions,
+    fixtures: config?.fixtures,
+  };
+
+  // Metadata
+  const { meta, isLoading: isMetaLoading } = useDocTypeMeta(connectionConfig, doctype);
+
+  // Column definitions from meta
+  const allColumns = useMemo((): ReportColumn[] => {
+    if (initialColumns) return initialColumns;
+    if (!meta) return [];
+    return meta.fields
+      .filter(
+        (f) =>
+          f.fieldtype !== "Section Break" &&
+          f.fieldtype !== "Column Break" &&
+          f.fieldtype !== "Tab Break",
+      )
+      .map((f) => ({
+        fieldname: f.fieldname,
+        label: f.label || f.fieldname,
+        fieldtype: f.fieldtype,
+        enabled: f.in_list_view ?? false,
+      }));
+  }, [initialColumns, meta]);
+
+  // Data fetching
+  const fetchFields = useMemo(() => {
+    const fieldNames = allColumns.map((c) => c.fieldname);
+    if (!fieldNames.includes("name")) {
+      fieldNames.unshift("name");
+    }
+    return fieldNames as readonly string[];
+  }, [allColumns]);
+
+  const collection = useFrappeCollection<{ name: string; doctype: string }>(
+    connectionConfig,
+    doctype,
+    {
+      fields: fetchFields as readonly ("name" | "doctype")[],
+      filters: filters as Partial<{ name: string; doctype: string }>,
+    },
+  );
+  const { data: rawData, isLoading } = useLiveQuery(
+    (q) => (collection ? q.from({ _list: collection }) : null),
+    [collection],
+  );
+  const data = useMemo(() => (rawData as Record<string, unknown>[] | undefined) ?? [], [rawData]);
+
+  // Group by state
+  const [groupBy, setGroupBy] = useState<GroupByConfig | null>(initialGroupBy ?? null);
+
+  // Enabled columns state
+  const [enabledColumns, setEnabledColumns] = useState<string[]>([]);
+
+  // Initialize enabled columns
+  useEffect(() => {
+    if (allColumns.length > 0 && enabledColumns.length === 0) {
+      const initial = allColumns.filter((c) => c.enabled).map((c) => c.fieldname);
+      if (initial.length === 0) {
+        setEnabledColumns(allColumns.slice(0, 5).map((c) => c.fieldname));
+      } else {
+        setEnabledColumns(initial);
+      }
+    }
+  }, [allColumns, enabledColumns.length]);
+
+  // Saved reports (Frappe-specific persistence layer)
+  const [savedReports, setSavedReports] = useState<SavedReport[]>([]);
+  const [saveDialogOpen, setSaveDialogOpen] = useState(false);
+  const [saveReportName, setSaveReportName] = useState("");
+
+  useEffect(() => {
+    let cancelled = false;
+    void (async () => {
+      const reports = await loadSavedReports(doctype);
+      if (!cancelled) {
+        setSavedReports(reports);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [doctype]);
+
+  const handleSaveReport = useCallback(() => {
+    if (!saveReportName.trim()) return;
+    const report: SavedReport = {
+      name: saveReportName.trim(),
+      columns: enabledColumns,
+      groupBy,
+      filters,
+    };
+    const updated = [...savedReports.filter((r) => r.name !== report.name), report];
+    setSavedReports(updated);
+    void persistSavedReports(doctype, updated);
+    setSaveDialogOpen(false);
+    setSaveReportName("");
+  }, [saveReportName, enabledColumns, groupBy, filters, savedReports, doctype]);
+
+  const handleLoadReport = useCallback((report: SavedReport) => {
+    setEnabledColumns(report.columns);
+    setGroupBy(report.groupBy);
+  }, []);
+
+  const handleDeleteReport = useCallback(
+    (name: string) => {
+      const updated = savedReports.filter((r) => r.name !== name);
+      setSavedReports(updated);
+      void persistSavedReports(doctype, updated);
+    },
+    [savedReports, doctype],
+  );
+
+  // CSV export handler
+  const handleExport = useCallback(
+    (exportData: Record<string, unknown>[]) => {
+      if (onExport) {
+        onExport(exportData);
+        return;
+      }
+
+      // Generate CSV
+      const cols = allColumns.filter((c) => enabledColumns.includes(c.fieldname));
+      const headers = cols.map((c) => c.label);
+      const csvRows = [headers.join(",")];
+
+      for (const row of exportData) {
+        const values = cols.map((col) => {
+          const val = row[col.fieldname];
+          if (val === null || val === undefined) return "";
+          const str = String(val);
+          if (str.includes(",") || str.includes('"') || str.includes("\n")) {
+            return `"${str.replace(/"/g, '""')}"`;
+          }
+          return str;
+        });
+        csvRows.push(values.join(","));
+      }
+
+      const csvContent = csvRows.join("\n");
+      const blob = new Blob([csvContent], { type: "text/csv;charset=utf-8;" });
+      downloadBlob(blob, `${doctype}_report.csv`);
+    },
+    [allColumns, enabledColumns, onExport, doctype],
+  );
+
+  if (isMetaLoading) {
+    return (
+      <YStack
+        {...knobProps.panelPadding}
+        alignItems="center"
+        justifyContent="center"
+        {...stackProps}
+      >
+        <Spinner size="large" />
+        <Text color="$color10" marginTop="$2">
+          {t("Loading {{doctype}} schema...", { doctype })}
+        </Text>
+      </YStack>
+    );
+  }
+
+  if (isLoading) {
+    return (
+      <YStack {...knobProps.panelPadding} alignItems="center" {...stackProps}>
+        <Spinner size="small" />
+        <Text color="$color10" fontSize="$2" marginTop="$1">
+          {t("Loading data...")}
+        </Text>
+      </YStack>
+    );
+  }
+
+  return (
+    <YStack flex={1} {...knobProps.borderRadius} {...stackProps}>
+      {/* Frappe-specific toolbar: Save/Load reports */}
+      <XStack
+        {...knobProps.panelPadding}
+        {...knobProps.surface}
+        {...knobProps.gap}
+        alignItems="center"
+        borderBottomWidth={1}
+        borderBottomColor="$borderColor"
+      >
+        <XStack flex={1} />
+        {/* Save */}
+        <Popover placement="bottom-end" open={saveDialogOpen} onOpenChange={setSaveDialogOpen}>
+          <Popover.Trigger asChild>
+            <Button size="$2" icon={FloppyDiskIcon}>
+              {t("Save")}
+            </Button>
+          </Popover.Trigger>
+          <Popover.Content
+            {...{ backgroundColor: "$background" }}
+            {...knobProps.borderRadius}
+            {...knobProps.panelPadding}
+            borderColor="$borderColor"
+          >
+            <Popover.Arrow borderWidth={1} borderColor="$borderColor" />
+            <YStack {...knobProps.gap} minWidth={220}>
+              <Text fontWeight="600" fontSize="$2">
+                {t("Save Report")}
+              </Text>
+              <Input
+                size="$3"
+                placeholder={t("Report name")}
+                value={saveReportName}
+                onChangeText={setSaveReportName}
+                onSubmitEditing={handleSaveReport}
+              />
+              <Button
+                size="$2"
+                theme="active"
+                onPress={handleSaveReport}
+                disabled={!saveReportName.trim()}
+              >
+                {t("Save")}
+              </Button>
+            </YStack>
+          </Popover.Content>
+        </Popover>
+
+        {/* Load */}
+        {savedReports.length > 0 && (
+          <Popover placement="bottom-end">
+            <Popover.Trigger asChild>
+              <Button size="$2" icon={FolderOpenIcon}>
+                {t("Load")}
+              </Button>
+            </Popover.Trigger>
+            <Popover.Content
+              {...{ backgroundColor: "$background" }}
+              {...knobProps.borderRadius}
+              {...knobProps.panelPadding}
+              borderColor="$borderColor"
+            >
+              <Popover.Arrow borderWidth={1} borderColor="$borderColor" />
+              <YStack gap="$1" minWidth={180}>
+                <Text fontWeight="600" fontSize="$2" color="$color10" padding="$1">
+                  {t("Saved Reports")}
+                </Text>
+                <Separator />
+                {savedReports.map((report) => (
+                  <XStack
+                    key={report.name}
+                    alignItems="center"
+                    justifyContent="space-between"
+                    padding="$2"
+                    {...knobProps.borderRadius}
+                    hoverStyle={{ backgroundColor: "$color2" }}
+                    cursor="pointer"
+                    onPress={() => handleLoadReport(report)}
+                  >
+                    <Text fontSize="$2" flex={1}>
+                      {report.name}
+                    </Text>
+                    <Button
+                      size="$1"
+                      chromeless
+                      icon={TrashIcon}
+                      onPress={(e) => {
+                        (e as unknown as { stopPropagation: () => void }).stopPropagation();
+                        handleDeleteReport(report.name);
+                      }}
+                      aria-label={t("Delete {{name}}", { name: report.name })}
+                    />
+                  </XStack>
+                ))}
+              </YStack>
+            </Popover.Content>
+          </Popover>
+        )}
+      </XStack>
+
+      {/* Delegate to generic ReportBuilder */}
+      <ReportBuilder
+        columns={allColumns}
+        data={data}
+        groupBy={groupBy ?? undefined}
+        onGroupByChange={setGroupBy}
+        onColumnsChange={setEnabledColumns}
+        onExport={handleExport}
+        showChart={showChart}
+        flex={1}
+      />
+    </YStack>
+  );
+}
+
+export type { ReportColumn, GroupByConfig } from "@multiplatform.one/components";

package/src/FrappeTable.stories.tsx

@@ -0,0 +1,220 @@
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { action } from "@multiplatform.one/storybook";
+import type { DataTableColumn } from "@multiplatform.one/table";
+import { Text } from "tamagui";
+import { FrappeTable } from "./FrappeTable";
+import { FrappeProvider } from "./FrappeProvider";
+
+export default {
+  title: "FrappeUI/FrappeTable",
+  component: FrappeTable,
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "A data table component connected to Frappe Live data with real-time updates, sorting, filtering, and pagination.",
+      },
+    },
+  },
+};
+
+interface Customer {
+  name: string;
+  doctype: string;
+  customer_name: string;
+  customer_type: string;
+  territory: string;
+  status: string;
+  creation: string;
+}
+
+const customerFixtures: Customer[] = [
+  {
+    name: "CUST-001",
+    doctype: "Customer",
+    customer_name: "Acme Corp",
+    customer_type: "Company",
+    territory: "United States",
+    status: "Active",
+    creation: "2025-01-15",
+  },
+  {
+    name: "CUST-002",
+    doctype: "Customer",
+    customer_name: "Global Tech",
+    customer_type: "Company",
+    territory: "Europe",
+    status: "Active",
+    creation: "2025-02-20",
+  },
+  {
+    name: "CUST-003",
+    doctype: "Customer",
+    customer_name: "John Smith",
+    customer_type: "Individual",
+    territory: "United States",
+    status: "Active",
+    creation: "2025-03-10",
+  },
+  {
+    name: "CUST-004",
+    doctype: "Customer",
+    customer_name: "Jane Doe",
+    customer_type: "Individual",
+    territory: "Asia Pacific",
+    status: "Inactive",
+    creation: "2024-12-05",
+  },
+  {
+    name: "CUST-005",
+    doctype: "Customer",
+    customer_name: "Tech Solutions",
+    customer_type: "Company",
+    territory: "Europe",
+    status: "Lead",
+    creation: "2025-04-01",
+  },
+  {
+    name: "CUST-006",
+    doctype: "Customer",
+    customer_name: "Startup Inc",
+    customer_type: "Company",
+    territory: "United States",
+    status: "Active",
+    creation: "2025-05-15",
+  },
+  {
+    name: "CUST-007",
+    doctype: "Customer",
+    customer_name: "Bob Wilson",
+    customer_type: "Individual",
+    territory: "Europe",
+    status: "Active",
+    creation: "2025-06-20",
+  },
+  {
+    name: "CUST-008",
+    doctype: "Customer",
+    customer_name: "Enterprise Ltd",
+    customer_type: "Company",
+    territory: "Asia Pacific",
+    status: "Inactive",
+    creation: "2024-11-30",
+  },
+];
+
+const customerColumns: DataTableColumn<Partial<Customer>>[] = [
+  { id: "name", header: "ID", accessorKey: "name" },
+  { id: "customer_name", header: "Customer Name", accessorKey: "customer_name" },
+  { id: "customer_type", header: "Type", accessorKey: "customer_type" },
+  { id: "territory", header: "Territory", accessorKey: "territory" },
+  {
+    id: "status",
+    header: "Status",
+    accessorKey: "status",
+    cell: ({ getValue }) => {
+      const status = getValue() as string;
+      const colors: Record<string, string> = {
+        Active: "#10B981",
+        Inactive: "#EF4444",
+        Lead: "#F59E0B",
+      };
+      return (
+        <Text color={colors[status] || "$gray11"} fontWeight="500">
+          {status}
+        </Text>
+      );
+    },
+  },
+  { id: "creation", header: "Created", accessorKey: "creation" },
+];
+
+export const Default = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ Customer: customerFixtures })}
+  >
+    <FrappeTable<Customer>
+      doctype="Customer"
+      columns={customerColumns}
+      onRowClick={action("onRowClick")}
+    />
+  </FrappeProvider>
+);
+Default.parameters = {
+  docs: {
+    description: {
+      story: "Basic data table connected to a Frappe Customer doctype.",
+    },
+  },
+};
+
+Default.storyName = "Main";
+export const WithPagination = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ Customer: customerFixtures })}
+  >
+    <FrappeTable<Customer>
+      doctype="Customer"
+      columns={customerColumns}
+      enablePagination
+      onRowClick={action("onRowClick")}
+    />
+  </FrappeProvider>
+);
+WithPagination.parameters = {
+  docs: {
+    description: {
+      story: "Table with pagination controls for large datasets.",
+    },
+  },
+};
+
+export const WithSavedFilters = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ Customer: customerFixtures })}
+  >
+    <FrappeTable<Customer>
+      doctype="Customer"
+      columns={customerColumns}
+      savedFilters
+      canCreateGlobalFilters
+      userId="admin@example.com"
+      onRowClick={action("onRowClick")}
+    />
+  </FrappeProvider>
+);
+WithSavedFilters.parameters = {
+  docs: {
+    description: {
+      story: "Table with saved filters feature for saving and loading filter presets.",
+    },
+  },
+};
+
+/**
+ * Server-side mode uses the Frappe REST API (getDocList) for filtering, sorting, and pagination.
+ * Requires a running Frappe backend. Fetches data with limit_start, limit_page_length, order_by, filters.
+ */
+export const ServerSide = () => (
+  <FrappeProvider baseURL="https://demo.frappe.cloud">
+    <FrappeTable<Customer>
+      doctype="Customer"
+      columns={customerColumns}
+      fields={["name", "customer_name", "customer_type", "territory", "status", "creation"]}
+      serverSide
+      onStateChange={action("onStateChange")}
+    />
+  </FrappeProvider>
+);
+ServerSide.parameters = {
+  docs: {
+    description: {
+      story:
+        "Server-side filtering, sorting, and pagination. Uses Frappe REST API (limit_start, limit_page_length, order_by, filters). Requires a running Frappe backend.",
+    },
+  },
+};