@multiplatform.one/frappe-ui 7.10.0 → 7.15.0

package/src/FrappeListView.tsx

@@ -6,12 +6,24 @@ import { useTranslation } from "react-i18next";
 import { Button, SearchInput, Spinner } from "@multiplatform.one/forms";
 import { Text, View, XStack, YStack, isWeb, useTheme, type YStackProps } from "tamagui";
 import { SavedFilterDropdown, useSavedFilters, type ParsedFilter } from "@multiplatform.one/table";
-import { Avatar, ViewSwitcher, componentColors } from "@multiplatform.one/components";
+import {
+  AsyncBoundary,
+  Avatar,
+  ListPageLayout,
+  PageHeader,
+  ViewSwitcher,
+  componentColors,
+  type ImageGridProps,
+} from "@multiplatform.one/components";
 import { pressTargetStyle, useResolvedKnobs } from "@multiplatform.one/theme";
 import { storage } from "@multiplatform.one/store";
 import { useFrappeConfig } from "./FrappeProvider";
-import { FrappeList } from "./FrappeList";
+import { FrappeList, type FrappeListProps } from "./FrappeList";
 import { FrappeTable } from "./FrappeTable";
+import { frappeRouteHref, useFrappeRouter } from "./frappeNavigation";
+import { connectionsFromMeta, type FrappeConnection } from "./frappeConnections";
+import { isPermissionError } from "./liveErrors";
+import { useConnectionFilters, type FrappeDoctypeFilter } from "./useConnectionFilters";
 
 interface ListFieldConfig {
   key: string;
@@ -19,7 +31,7 @@ interface ListFieldConfig {
   render?: (value: any, doc: any) => React.ReactNode;
 }
 
-export type ListViewMode = "list" | "table";
+export type ListViewMode = "list" | "table" | "grid";
 
 export interface FrappeListViewProps<TDoc extends { name: string; doctype: string }> extends Omit<
   YStackProps,
@@ -27,12 +39,58 @@ export interface FrappeListViewProps<TDoc extends { name: string; doctype: strin
 > {
   doctype: string;
   fields?: readonly (keyof TDoc & string)[];
-  filters?: Partial<TDoc> | Array<[keyof TDoc & string, string, unknown]>;
+  /**
+   * Doctypes linking back to this one (desk Connections). A four-part filter
+   * on one of them, `[doctype, field, operator, value]`, narrows this list to
+   * the records its matching rows name. Defaults to the doctype's meta.links.
+   */
+  connections?: readonly FrappeConnection[];
+  filters?: Partial<TDoc> | Array<[keyof TDoc & string, string, unknown] | FrappeDoctypeFilter>;
   defaultViewMode?: ListViewMode;
+  /** Controlled view mode; the stored per-doctype choice is then ignored. */
+  viewMode?: ListViewMode;
+  onViewModeChange?: (mode: ListViewMode) => void;
   onItemClick?: (doc: Partial<TDoc>) => void;
   onAdd?: () => void;
+  /**
+   * The path the doctype's pages live under (`/moves`). Given, the view is
+   * the doctype's list page: it carries the list page template with the
+   * doctype as its title, a row opens `route/<name>` and Add opens
+   * `route/new` through the FrappeProvider's navigation. Add waits for the
+   * doctype's meta, so a reader who cannot load it is not offered a form.
+   */
+  route?: string;
+  /**
+   * The query the list reads, beyond fields and filters. Give a route loader
+   * the same order and limit (`loadDocList`) so its server page and the live
+   * page match; `initialRows` is that server page.
+   */
+  orderBy?: FrappeListProps<TDoc>["orderBy"];
+  limit?: number;
+  initialRows?: readonly Partial<TDoc>[];
   columns?: DataTableColumn<Partial<TDoc>>[];
   displayFields?: ListFieldConfig[];
+  /**
+   * Per-row card slot. Given, the view gains a card grid (`grid` mode, the
+   * catalog ImageGrid) that draws each row with it; loading, empty and error
+   * stay the view's own states.
+   */
+  renderCard?: (doc: Partial<TDoc>, index: number) => React.ReactNode;
+  /** Card grid: column count, tile rung and media aspect. */
+  gridProps?: Pick<ImageGridProps<Partial<TDoc>>, "columns" | "tileSize" | "mediaAspect">;
+  /** Replaces the default empty message in list and card modes. */
+  emptyState?: React.ReactNode;
+  /**
+   * Error-state retry. Defaults to remounting the list, which restarts its
+   * sync only when nothing else still holds the failed collection.
+   */
+  onRetry?: () => void;
+  /** Rows revealed per page in list and card modes (default 20). */
+  pageSize?: number;
+  /** False drops the list/card search band (a screen that owns its own search). */
+  showSearch?: boolean;
+  /** False renders the view without its card surface, flush in the page. */
+  surface?: boolean;
   showToolbar?: boolean;
   showFilterSidebar?: boolean;
   /** @deprecated The toolbar always renders the List/Table switcher now. */
@@ -90,7 +148,7 @@ function resolveImageUrl(value: unknown, baseURL: string): string {
 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;
+    if (stored === "list" || stored === "table" || stored === "grid") return stored;
   } catch {
     // storage not available
   }
@@ -114,12 +172,26 @@ async function setStoredViewMode(doctype: string, mode: ListViewMode): Promise<v
 export function FrappeListView<TDoc extends { name: string; doctype: string }>({
   doctype,
   fields,
+  connections,
   filters,
   defaultViewMode = "list",
-  onItemClick,
-  onAdd,
+  viewMode: controlledViewMode,
+  onViewModeChange,
+  onItemClick: onItemClickProp,
+  onAdd: onAddProp,
+  route,
+  orderBy,
+  limit,
+  initialRows,
   columns,
   displayFields,
+  renderCard,
+  gridProps,
+  emptyState,
+  onRetry,
+  pageSize,
+  showSearch = true,
+  surface = true,
   showToolbar = true,
   showFilterSidebar = false,
   // deprecated: switcher always renders; destructured so it stays out of stackProps
@@ -130,6 +202,7 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
   ...stackProps
 }: FrappeListViewProps<TDoc>) {
   const config = useFrappeConfig();
+  const navigate = useFrappeRouter()?.navigate;
   const { knobProps } = useResolvedKnobs();
   const { t } = useTranslation();
   const theme = useTheme();
@@ -153,7 +226,10 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
     fixtures: config?.fixtures,
   };
 
-  const [viewMode, setViewModeState] = useState<ListViewMode>(defaultViewMode);
+  const [storedViewMode, setViewModeState] = useState<ListViewMode>(defaultViewMode);
+  const requestedViewMode = controlledViewMode ?? storedViewMode;
+  const viewMode: ListViewMode =
+    requestedViewMode === "grid" && !renderCard ? "list" : requestedViewMode;
 
   useEffect(() => {
     let cancelled = false;
@@ -171,10 +247,12 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
 
   const setViewMode = useCallback(
     (mode: ListViewMode) => {
+      onViewModeChange?.(mode);
+      if (controlledViewMode !== undefined) return;
       setViewModeState(mode);
       void setStoredViewMode(doctype, mode);
     },
-    [doctype],
+    [doctype, controlledViewMode, onViewModeChange],
   );
 
   const {
@@ -183,6 +261,27 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
     error: metaError,
   } = useDocTypeMeta(connectionConfig, doctype);
 
+  const onItemClick =
+    onItemClickProp ??
+    (route !== undefined && navigate
+      ? (doc: Partial<TDoc>) => {
+          if (doc.name) navigate(frappeRouteHref(route, { mode: "view", name: doc.name }));
+        }
+      : undefined);
+  const onAdd =
+    onAddProp ??
+    (route !== undefined && navigate && meta
+      ? () => navigate(frappeRouteHref(route, { mode: "create" }))
+      : undefined);
+  const asPage = (view: React.ReactElement) =>
+    route === undefined ? (
+      view
+    ) : (
+      <ListPageLayout scroll={false} header={<PageHeader title={doctype} divider={false} />}>
+        {view}
+      </ListPageLayout>
+    );
+
   // Guest fallback: DocType meta is permission-gated (Guests get 403) while
   // the documents themselves are often guest-readable. Peek one doc with
   // fields=["*"] and derive display fields from its keys so the views render
@@ -352,6 +451,18 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
     setActiveFilters(filters);
   }, [filters]);
 
+  const effectiveConnections = useMemo(
+    () => connections ?? (isMetaLoading ? undefined : connectionsFromMeta(meta)),
+    [connections, isMetaLoading, meta],
+  );
+  const linkFilters = useConnectionFilters(
+    connectionConfig,
+    doctype,
+    activeFilters as Parameters<typeof useConnectionFilters>[2],
+    effectiveConnections,
+  );
+  const resolvedFilters = linkFilters.filters as typeof activeFilters;
+
   // List-mode search: a debounced server-side `like` on the doctype's title
   // field, merged into the filters useFrappePagination already accepts (the
   // pagination layer has no orFilters plumbing, so one well-chosen field
@@ -368,21 +479,21 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
 
   const listFilters = useMemo(() => {
     const query = debouncedSearch.trim();
-    if (!query) return activeFilters;
+    if (!query) return resolvedFilters;
     const searchFilter = [searchField, "like", `%${query}%`] as [
       keyof TDoc & string,
       string,
       unknown,
     ];
-    if (!activeFilters) return [searchFilter];
-    if (Array.isArray(activeFilters)) return [...activeFilters, searchFilter];
+    if (!resolvedFilters) return [searchFilter];
+    if (Array.isArray(resolvedFilters)) return [...resolvedFilters, searchFilter];
     return [
-      ...Object.entries(activeFilters).map(
+      ...Object.entries(resolvedFilters).map(
         ([key, value]) => [key, "=", value] as [keyof TDoc & string, string, unknown],
       ),
       searchFilter,
     ];
-  }, [activeFilters, debouncedSearch, searchField]);
+  }, [resolvedFilters, debouncedSearch, searchField]);
 
   // Axiom 6 / DG-TBL-06: zero rows under active filters or search must not
   // render the same chrome as a truly empty doctype — the no-results message
@@ -423,8 +534,10 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
     [savedFiltersHook],
   );
 
-  if (isMetaLoading) {
-    return (
+  // Named fields need no schema to read or draw: the view renders now (on
+  // the server too) and labels settle when meta lands.
+  if (isMetaLoading && !fields) {
+    return asPage(
       <YStack
         {...knobProps.panelPadding}
         alignItems="center"
@@ -435,7 +548,7 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
         <Text {...knobProps.body} color={knobProps.textAccentColor} marginTop="$2">
           {t("Loading {{doctype}} schema...", { doctype })}
         </Text>
-      </YStack>
+      </YStack>,
     );
   }
 
@@ -456,6 +569,7 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
         <XStack alignItems="center" {...knobProps.gap}>
           <ViewSwitcher
             views={[
+              ...(renderCard ? [{ type: "grid", label: t("Cards") }] : []),
               { type: "list", label: t("List") },
               { type: "table", label: t("Table") },
             ]}
@@ -576,17 +690,23 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
   );
 
   const renderContent = () => {
-    if (viewMode === "list") {
+    if (viewMode === "list" || viewMode === "grid") {
+      const isGrid = viewMode === "grid";
       return (
-        <YStack flex={1}>
-          {renderListSearch()}
+        <YStack flex={isGrid ? undefined : 1}>
+          {showSearch ? renderListSearch() : null}
           <FrappeList
-            key={`list-${refreshKey}`}
+            key={`${viewMode}-${refreshKey}`}
+            layout={isGrid ? "grid" : "list"}
+            gridProps={gridProps}
+            emptyState={emptyState}
+            pageSize={pageSize}
+            onRetry={onRetry ?? handleRefresh}
             doctype={doctype}
             fields={effectiveFields as readonly ("name" | "doctype")[]}
             filters={listFilters as Partial<{ name: string; doctype: string }>}
             renderItem={
-              renderListItem as unknown as (
+              (isGrid && renderCard ? renderCard : renderListItem) as unknown as (
                 item: Partial<{ name: string; doctype: string }>,
                 index: number,
               ) => React.ReactNode
@@ -599,6 +719,11 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
             baseURL={finalBaseURL}
             auth={finalAuth}
             syncOptions={finalSyncOptions}
+            orderBy={orderBy as FrappeListProps<{ name: string; doctype: string }>["orderBy"]}
+            limit={limit}
+            initialRows={
+              initialRows as FrappeListProps<{ name: string; doctype: string }>["initialRows"]
+            }
             // Only override when narrowing is active: FrappeList's own
             // "No {doctype} records found" stays the true-empty message.
             {...(noResultsMessage ? { emptyMessage: noResultsMessage } : {})}
@@ -612,7 +737,7 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
         key={`table-${refreshKey}`}
         doctype={doctype}
         fields={effectiveFields}
-        filters={activeFilters}
+        filters={resolvedFilters as Parameters<typeof FrappeTable<TDoc>>[0]["filters"]}
         columns={effectiveColumns}
         onRowClick={onItemClick}
         baseURL={finalBaseURL}
@@ -622,24 +747,45 @@ export function FrappeListView<TDoc extends { name: string; doctype: string }>({
     );
   };
 
-  return (
+  // A connection filter's matching records are known only once its linked
+  // rows are read; until then the view waits instead of listing everything.
+  const renderResolvedContent = () => {
+    if (linkFilters.error) {
+      return (
+        <AsyncBoundary
+          layout="list"
+          error={linkFilters.error}
+          errorTitle={
+            isPermissionError(linkFilters.error)
+              ? t("You do not have permission to view {{doctype}}", { doctype })
+              : t("Error loading {{doctype}}", { doctype })
+          }
+        />
+      );
+    }
+    if (linkFilters.pending) return <AsyncBoundary layout="list" loading />;
+    return renderContent();
+  };
+
+  return asPage(
     <YStack
-      flex={1}
-      {...knobProps.surface}
-      {...knobProps.containerRadius}
-      overflow="hidden"
+      flex={viewMode === "grid" ? undefined : 1}
+      {...(surface ? knobProps.surface : {})}
+      {...(surface ? knobProps.containerRadius : {})}
+      overflow={surface ? "hidden" : undefined}
       testID={`${doctype.toLowerCase()}-list`}
       {...stackProps}
     >
       {renderToolbar()}
+      {linkFilters.readers}
       {showFilterSidebar ? (
         <XStack flex={1}>
           {renderFilterSidebar()}
-          <YStack flex={1}>{renderContent()}</YStack>
+          <YStack flex={1}>{renderResolvedContent()}</YStack>
         </XStack>
       ) : (
-        renderContent()
+        renderResolvedContent()
       )}
-    </YStack>
+    </YStack>,
   );
 }