@multiplatform.one/frappe-ui 6.0.0

package/src/FrappeListView.tsx

@@ -0,0 +1,421 @@
+import { useDocTypeMeta } from "@multiplatform.one/frappe";
+import type { DataTableColumn } from "@multiplatform.one/table";
+import { ArrowsClockwiseIcon, ListIcon, PlusIcon, TableIcon } from "@phosphor-icons/react";
+import React, { useState, useMemo, useCallback, useEffect } from "react";
+import { useTranslation } from "react-i18next";
+import { Button, Spinner, Text, XStack, YStack, type YStackProps } from "tamagui";
+import { SavedFilterDropdown, useSavedFilters, type ParsedFilter } from "@multiplatform.one/table";
+import { ViewSwitcher } from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { storage } from "@multiplatform.one/store";
+import { useFrappeConfig } from "./FrappeProvider";
+import { FrappeList } from "./FrappeList";
+import { FrappeTable } from "./FrappeTable";
+
+interface ListFieldConfig {
+  key: string;
+  label?: string;
+  render?: (value: any, doc: any) => React.ReactNode;
+}
+
+export type ListViewMode = "list" | "table";
+
+export interface FrappeListViewProps<TDoc extends { name: string; doctype: string }> extends Omit<
+  YStackProps,
+  "children"
+> {
+  doctype: string;
+  fields?: readonly (keyof TDoc & string)[];
+  filters?: Partial<TDoc> | Array<[keyof TDoc & string, string, unknown]>;
+  defaultViewMode?: ListViewMode;
+  onItemClick?: (doc: Partial<TDoc>) => void;
+  onAdd?: () => void;
+  columns?: DataTableColumn<Partial<TDoc>>[];
+  displayFields?: ListFieldConfig[];
+  showToolbar?: boolean;
+  showFilterSidebar?: boolean;
+  enableViewSwitcher?: boolean;
+  baseURL?: string;
+  auth?: { useToken?: boolean; token?: string; type?: string };
+  syncOptions?: Record<string, unknown>;
+}
+
+const storageKeyPrefix = "frappe-listview-";
+
+async function getStoredViewMode(doctype: string): Promise<ListViewMode | null> {
+  try {
+    const stored = await Promise.resolve(storage.getItem(`${storageKeyPrefix}${doctype}`));
+    if (stored === "list" || stored === "table") return stored;
+  } catch {
+    // storage not available
+  }
+  return null;
+}
+
+async function setStoredViewMode(doctype: string, mode: ListViewMode): Promise<void> {
+  try {
+    await Promise.resolve(storage.setItem(`${storageKeyPrefix}${doctype}`, mode));
+  } catch {
+    // storage not available
+  }
+}
+
+/**
+ * Unified list/table view for a Frappe DocType.
+ *
+ * Delegates to `FrappeList` (which delegates to generic `List`) or
+ * `FrappeTable` (which delegates to `DataTable`) based on the view mode.
+ */
+export function FrappeListView<TDoc extends { name: string; doctype: string }>({
+  doctype,
+  fields,
+  filters,
+  defaultViewMode = "list",
+  onItemClick,
+  onAdd,
+  columns,
+  displayFields,
+  showToolbar = true,
+  showFilterSidebar = false,
+  enableViewSwitcher = false,
+  baseURL,
+  auth,
+  syncOptions,
+  ...stackProps
+}: FrappeListViewProps<TDoc>) {
+  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("FrappeListView requires baseURL prop or FrappeProvider with baseURL");
+  }
+
+  const connectionConfig = {
+    baseURL: finalBaseURL,
+    socketPort: config?.socketPort,
+    auth: finalAuth,
+    syncOptions: finalSyncOptions,
+    fixtures: config?.fixtures,
+  };
+
+  const [viewMode, setViewModeState] = useState<ListViewMode>(defaultViewMode);
+
+  useEffect(() => {
+    let cancelled = false;
+    setViewModeState(defaultViewMode);
+    void (async () => {
+      const storedMode = await getStoredViewMode(doctype);
+      if (!cancelled && storedMode) {
+        setViewModeState(storedMode);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [doctype, defaultViewMode]);
+
+  const setViewMode = useCallback(
+    (mode: ListViewMode) => {
+      setViewModeState(mode);
+      void setStoredViewMode(doctype, mode);
+    },
+    [doctype],
+  );
+
+  const { meta, isLoading: isMetaLoading } = useDocTypeMeta(connectionConfig, doctype);
+
+  const effectiveFields = useMemo(() => {
+    if (fields) return fields;
+    if (!meta) return ["name" as keyof TDoc & string];
+    const listFields = meta.fields
+      .filter((f) => f.in_list_view && f.fieldname !== "name")
+      .map((f) => f.fieldname as keyof TDoc & string);
+    return ["name" as keyof TDoc & string, ...listFields];
+  }, [fields, meta]);
+
+  const effectiveDisplayFields = useMemo((): ListFieldConfig[] => {
+    if (displayFields) return displayFields;
+    if (!meta) return [{ key: "name", label: t("Name") }];
+    const metaListFields = meta.fields.filter((f) => f.in_list_view);
+    if (metaListFields.length === 0) return [{ key: "name", label: t("Name") }];
+    return metaListFields.map((f) => ({
+      key: f.fieldname,
+      label: f.label || f.fieldname,
+    }));
+  }, [displayFields, meta, t]);
+
+  const renderListItem = useCallback(
+    (doc: Partial<TDoc>) => {
+      if (effectiveDisplayFields.length === 0) {
+        return <Text>{doc.name}</Text>;
+      }
+      return (
+        <YStack gap="$0.5" paddingVertical="$2" paddingHorizontal="$3">
+          {effectiveDisplayFields.map((field) => {
+            const value = (doc as any)[field.key];
+            return (
+              <XStack key={field.key} gap="$2" alignItems="center">
+                {field.label && (
+                  <Text fontSize="$2" color="$color10" minWidth={80}>
+                    {field.label}:
+                  </Text>
+                )}
+                <Text
+                  fontSize={field.label ? "$3" : "$4"}
+                  fontWeight={field.label ? "normal" : "600"}
+                >
+                  {field.render ? field.render(value, doc) : value || "-"}
+                </Text>
+              </XStack>
+            );
+          })}
+        </YStack>
+      );
+    },
+    [effectiveDisplayFields],
+  );
+
+  const effectiveColumns = useMemo((): DataTableColumn<Partial<TDoc>>[] => {
+    if (columns) return columns;
+    if (!meta) {
+      return [{ accessorKey: "name" as string, header: t("Name") }] as DataTableColumn<
+        Partial<TDoc>
+      >[];
+    }
+    const metaListFields = meta.fields.filter((f) => f.in_list_view);
+    if (metaListFields.length === 0) {
+      return [{ accessorKey: "name" as string, header: t("Name") }] as DataTableColumn<
+        Partial<TDoc>
+      >[];
+    }
+    return metaListFields.map(
+      (f) =>
+        ({
+          accessorKey: f.fieldname as string,
+          header: f.label || f.fieldname,
+        }) as DataTableColumn<Partial<TDoc>>,
+    );
+  }, [columns, meta, t]);
+
+  const standardFilterFields = useMemo(() => {
+    if (!meta) return [];
+    return meta.fields.filter((f) => f.in_standard_filter);
+  }, [meta]);
+
+  const savedFiltersHook = useSavedFilters();
+
+  const [activeFilters, setActiveFilters] = useState(filters);
+
+  useEffect(() => {
+    setActiveFilters(filters);
+  }, [filters]);
+
+  const [refreshKey, setRefreshKey] = useState(0);
+  const handleRefresh = useCallback(() => {
+    setRefreshKey((prev) => prev + 1);
+  }, []);
+
+  const handleSelectSavedFilter = useCallback(
+    (filter: ParsedFilter | null) => {
+      if (filter) {
+        setActiveFilters(filter.filters as typeof filters);
+      } else {
+        setActiveFilters(filters);
+      }
+    },
+    [filters],
+  );
+
+  const handleDeleteFilter = useCallback(
+    async (name: string) => {
+      await savedFiltersHook.deleteFilter(name);
+    },
+    [savedFiltersHook],
+  );
+
+  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>
+    );
+  }
+
+  const renderToolbar = () => {
+    if (!showToolbar) return null;
+
+    return (
+      <XStack
+        {...knobProps.panelPadding}
+        {...knobProps.surface}
+        alignItems="center"
+        justifyContent="space-between"
+        borderBottomWidth={1}
+        borderBottomColor="$borderColor"
+      >
+        <XStack alignItems="center" {...knobProps.gap}>
+          <Button
+            size="$2"
+            chromeless={viewMode !== "list"}
+            theme={viewMode === "list" ? "blue" : undefined}
+            onPress={() => setViewMode("list")}
+            icon={ListIcon}
+            aria-label={t("List view")}
+          />
+          <Button
+            size="$2"
+            chromeless={viewMode !== "table"}
+            theme={viewMode === "table" ? "blue" : undefined}
+            onPress={() => setViewMode("table")}
+            icon={TableIcon}
+            aria-label={t("Table view")}
+          />
+          {enableViewSwitcher && (
+            <ViewSwitcher
+              views={[
+                { type: "list", label: t("List") },
+                { type: "table", label: t("Table") },
+              ]}
+              currentView={viewMode}
+              onViewChange={(v) => setViewMode(v as ListViewMode)}
+            />
+          )}
+        </XStack>
+
+        <XStack alignItems="center" {...knobProps.gap}>
+          <Button
+            size="$2"
+            chromeless
+            icon={ArrowsClockwiseIcon}
+            onPress={handleRefresh}
+            aria-label={t("Refresh")}
+          />
+          {onAdd && (
+            <Button size="$2" theme="active" icon={PlusIcon} onPress={onAdd}>
+              {t("Add {{doctype}}", { doctype })}
+            </Button>
+          )}
+        </XStack>
+      </XStack>
+    );
+  };
+
+  const renderFilterSidebar = () => {
+    if (!showFilterSidebar) return null;
+
+    return (
+      <YStack
+        width={220}
+        {...knobProps.surface}
+        borderRightWidth={1}
+        borderRightColor="$borderColor"
+        {...knobProps.panelPadding}
+        {...knobProps.gap}
+      >
+        <Text fontWeight="600" fontSize="$2" color="$color10">
+          {t("Filters")}
+        </Text>
+        {standardFilterFields.length > 0 && (
+          <YStack {...knobProps.gap}>
+            {standardFilterFields.map((field) => (
+              <YStack key={field.fieldname} gap="$1">
+                <Text fontSize="$1" color="$color10">
+                  {field.label || field.fieldname}
+                </Text>
+                <Text fontSize="$2" color="$color10">
+                  {field.fieldtype === "Select" ? field.options || "—" : "—"}
+                </Text>
+              </YStack>
+            ))}
+          </YStack>
+        )}
+        {savedFiltersHook.filters.length > 0 && (
+          <YStack {...knobProps.gap}>
+            <Text fontWeight="600" fontSize="$2" color="$color10">
+              {t("Saved Filters")}
+            </Text>
+            <SavedFilterDropdown
+              filters={savedFiltersHook.filters}
+              selectedFilter={null}
+              onSelectFilter={handleSelectSavedFilter}
+              onDeleteFilter={handleDeleteFilter}
+            />
+          </YStack>
+        )}
+      </YStack>
+    );
+  };
+
+  const renderContent = () => {
+    if (viewMode === "list") {
+      return (
+        <FrappeList
+          key={`list-${refreshKey}`}
+          doctype={doctype}
+          fields={effectiveFields as readonly ("name" | "doctype")[]}
+          filters={activeFilters as Partial<{ name: string; doctype: string }>}
+          renderItem={
+            renderListItem as unknown as (
+              item: Partial<{ name: string; doctype: string }>,
+              index: number,
+            ) => React.ReactNode
+          }
+          onItemClick={
+            onItemClick as unknown as
+              | ((item: Partial<{ name: string; doctype: string }>) => void)
+              | undefined
+          }
+          baseURL={finalBaseURL}
+          auth={finalAuth}
+          syncOptions={finalSyncOptions}
+        />
+      );
+    }
+
+    return (
+      <FrappeTable
+        key={`table-${refreshKey}`}
+        doctype={doctype}
+        fields={effectiveFields}
+        filters={activeFilters}
+        columns={effectiveColumns}
+        onRowClick={onItemClick}
+        baseURL={finalBaseURL}
+        auth={finalAuth}
+        syncOptions={finalSyncOptions}
+      />
+    );
+  };
+
+  return (
+    <YStack
+      flex={1}
+      {...knobProps.borderRadius}
+      testID={`${doctype.toLowerCase()}-list`}
+      {...stackProps}
+    >
+      {renderToolbar()}
+      {showFilterSidebar ? (
+        <XStack flex={1}>
+          {renderFilterSidebar()}
+          <YStack flex={1}>{renderContent()}</YStack>
+        </XStack>
+      ) : (
+        renderContent()
+      )}
+    </YStack>
+  );
+}

package/src/FrappeProvider.tsx

@@ -0,0 +1,144 @@
+import type { FixtureProvider } from "@multiplatform.one/frappe";
+import React, { createContext, use, useContext } from "react";
+
+/**
+ * Configuration for the Frappe connection.
+ *
+ * @category Types
+ */
+export interface FrappeConfig {
+  /** The base URL of the Frappe server */
+  baseURL: string;
+  /**
+   * Override the port used for the Socket.IO realtime connection.
+   *
+   * In development the Frappe SocketIO server typically runs on a separate
+   * port (e.g. `FRAPPE_SOCKETIO_PORT=9000`) while the HTTP API is on 8000.
+   * Set this so the client connects to the right place without a reverse proxy.
+   *
+   * When omitted the port from `baseURL` is used, which is correct behind a
+   * production reverse proxy that routes `/socket.io` to the SocketIO backend.
+   */
+  socketPort?: number;
+  /** Authentication configuration */
+  auth?: {
+    /** Whether to use token-based authentication */
+    useToken?: boolean;
+    /** The authentication token */
+    token?: string;
+    /** The authentication type */
+    type?: string;
+  };
+  /** Sync options for the live data engine */
+  syncOptions?: any;
+  /** Fixture provider for testing */
+  fixtures?: FixtureProvider;
+}
+
+const FrappeContext = createContext<FrappeConfig | undefined>(undefined);
+
+/**
+ * Props for the FrappeProvider component.
+ *
+ * @category Types
+ */
+export interface FrappeProviderProps {
+  /** Child components */
+  children: React.ReactNode;
+  /** The base URL of the Frappe server */
+  baseURL: string;
+  /** Override port for Socket.IO realtime connection (e.g. 9000 in dev). */
+  socketPort?: number;
+  /** Authentication configuration */
+  auth?: {
+    /** Whether to use token-based authentication */
+    useToken?: boolean;
+    /** The authentication token */
+    token?: string;
+    /** The authentication type */
+    type?: string;
+  };
+  /** Sync options for the live data engine */
+  syncOptions?: any;
+  /** Fixture provider for testing */
+  fixtures?: FixtureProvider;
+}
+
+/**
+ * Provider component for Frappe configuration.
+ *
+ * Wraps your app to provide Frappe configuration to all child components.
+ * Components using FrappeTable, useFrappeConfig, or useFrappeContext will
+ * read their configuration from this provider.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <FrappeProvider
+ *       baseURL="https://mysite.frappe.cloud"
+ *       auth={{ useToken: true, token: 'api-key-123' }}
+ *     >
+ *       <MyApp />
+ *     </FrappeProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @category Components
+ */
+export function FrappeProvider({
+  children,
+  baseURL,
+  socketPort,
+  auth,
+  syncOptions,
+  fixtures,
+}: FrappeProviderProps) {
+  const value = React.useMemo(
+    () => ({ baseURL, socketPort, auth, syncOptions, fixtures }),
+    [baseURL, socketPort, auth, syncOptions, fixtures],
+  );
+
+  return <FrappeContext.Provider value={value}>{children}</FrappeContext.Provider>;
+}
+
+/**
+ * Hook to read the FrappeConfig from context.
+ * This uses the traditional useContext() hook.
+ *
+ * @returns The FrappeConfig if a FrappeProvider is present, undefined otherwise
+ */
+export function useFrappeConfig(): FrappeConfig | undefined {
+  return useContext(FrappeContext);
+}
+
+/**
+ * React 19 use() hook wrapper for reading FrappeContext.
+ *
+ * Unlike useFrappeConfig(), this can be called conditionally - after if statements,
+ * early returns, or inside loops. This is a key benefit of React 19's use() hook.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent({ disabled }: { disabled: boolean }) {
+ *   // Early return before context read - not possible with useContext!
+ *   if (disabled) {
+ *     return <DisabledView />;
+ *   }
+ *
+ *   // With use(), we can read context after conditional returns
+ *   const config = useFrappeContext();
+ *   if (!config) {
+ *     return <NoConfigView />;
+ *   }
+ *
+ *   return <EnabledView config={config} />;
+ * }
+ * ```
+ *
+ * @returns The FrappeConfig if a FrappeProvider is present, undefined otherwise
+ */
+export function useFrappeContext(): FrappeConfig | undefined {
+  return use(FrappeContext);
+}