@multiplatform.one/frappe-ui 6.0.0

package/src/FrappeKanban.tsx

@@ -0,0 +1,190 @@
+import { useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
+import {
+  Kanban,
+  type KanbanColumn as GenericKanbanColumn,
+  type KanbanProps,
+} from "@multiplatform.one/components";
+import React, { useMemo, useCallback } from "react";
+import { Card, Text, YStack } from "tamagui";
+
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useFrappeConfig } from "./FrappeProvider";
+
+/**
+ * Configuration for a single Kanban column.
+ */
+export interface KanbanColumn {
+  value: string;
+  title: string;
+  color?: string;
+}
+
+/**
+ * Render function for custom card content.
+ */
+export type KanbanCardRenderer<TDoc> = (
+  card: Partial<TDoc>,
+  defaultContent: React.ReactNode,
+) => React.ReactNode;
+
+export interface FrappeKanbanProps<TDoc extends { name: string; doctype: string }> extends Omit<
+  KanbanProps<Partial<TDoc>>,
+  "columns" | "renderCard" | "onCardMove"
+> {
+  baseURL?: string;
+  auth?: { useToken?: boolean; token?: string; type?: string };
+  syncOptions?: any;
+  doctype: string;
+  fields?: readonly (keyof TDoc & string)[];
+  filters?: Partial<TDoc> | Array<[keyof TDoc & string, string, any]>;
+  statusField: keyof TDoc & string;
+  columns: KanbanColumn[];
+  titleField?: keyof TDoc & string;
+  descriptionField?: keyof TDoc & string;
+  renderCard?: (item: Partial<TDoc>) => React.ReactNode;
+  onCardClick?: (card: Partial<TDoc>) => void;
+  onCardMove?: (cardName: string, fromStatus: string, toStatus: string) => void | Promise<void>;
+  enableCardCreation?: boolean;
+  onCreateCard?: (status: string) => void;
+  loading?: React.ReactNode;
+  error?: (error: Error) => React.ReactNode;
+}
+
+/**
+ * Thin Frappe wrapper around the generic Kanban component.
+ *
+ * Fetches data via `useFrappeCollection` / `useLiveQuery`, groups cards
+ * by `statusField`, and passes the grouped columns to the generic
+ * `Kanban` from `@multiplatform.one/components`.
+ */
+export function FrappeKanban<TDoc extends { name: string; doctype: string }>({
+  baseURL,
+  auth,
+  syncOptions,
+  doctype,
+  fields,
+  filters,
+  statusField,
+  columns,
+  titleField,
+  descriptionField,
+  renderCard,
+  onCardClick,
+  onCardMove,
+  enableCardCreation: _enableCardCreation = false,
+  onCreateCard: _onCreateCard,
+  loading: _loading,
+  error: _error,
+  ...kanbanProps
+}: FrappeKanbanProps<TDoc>) {
+  const config = useFrappeConfig();
+  const { knobProps } = useResolvedKnobs();
+
+  const finalBaseURL = baseURL ?? config?.baseURL;
+  const finalAuth = auth ?? config?.auth;
+  const finalSyncOptions = syncOptions ?? config?.syncOptions;
+
+  if (!finalBaseURL) {
+    throw new Error("FrappeKanban requires baseURL prop or FrappeProvider with baseURL");
+  }
+
+  // Ensure required fields are fetched
+  const effectiveFields = useMemo(() => {
+    if (!fields) return undefined;
+    const fieldSet = new Set(fields);
+    fieldSet.add(statusField);
+    fieldSet.add("name" as keyof TDoc & string);
+    if (titleField) fieldSet.add(titleField);
+    if (descriptionField) fieldSet.add(descriptionField);
+    return Array.from(fieldSet) as (keyof TDoc & string)[];
+  }, [fields, statusField, titleField, descriptionField]);
+
+  const collection = useFrappeCollection<TDoc>(
+    {
+      baseURL: finalBaseURL,
+      socketPort: config?.socketPort,
+      auth: finalAuth,
+      syncOptions: finalSyncOptions,
+      fixtures: config?.fixtures,
+    },
+    doctype,
+    { fields: effectiveFields, filters },
+  );
+  const { data: rawData, isLoading } = useLiveQuery(
+    (q) => (collection ? q.from({ _list: collection }) : null),
+    [collection],
+  );
+  const cards = useMemo(() => (rawData as TDoc[] | undefined) ?? [], [rawData]);
+
+  // Group cards by status into generic KanbanColumn format
+  const genericColumns = useMemo((): GenericKanbanColumn<Partial<TDoc>>[] => {
+    const grouped: Record<string, Partial<TDoc>[]> = {};
+    for (const column of columns) {
+      grouped[column.value] = [];
+    }
+    for (const card of cards) {
+      const status = (card as any)[statusField];
+      if (status && grouped[status]) {
+        grouped[status].push(card);
+      }
+    }
+    return columns.map((col) => ({
+      id: col.value,
+      title: col.title,
+      items: grouped[col.value] || [],
+      color: col.color,
+    }));
+  }, [cards, columns, statusField]);
+
+  // Default card renderer
+  const effectiveRenderCard =
+    renderCard ??
+    ((item: Partial<TDoc>) => {
+      const title = titleField ? (item as any)[titleField] : item.name;
+      const desc = descriptionField ? (item as any)[descriptionField] : undefined;
+      return (
+        <Card size={knobProps.sizeToken} {...knobProps.borderRadius}>
+          <YStack {...knobProps.panelPadding}>
+            <Text fontWeight="500" fontSize={knobProps.sizeToken}>
+              {title || item.name}
+            </Text>
+            {desc && (
+              <Text fontSize="$2" color="$color10" marginTop="$1">
+                {desc}
+              </Text>
+            )}
+          </YStack>
+        </Card>
+      );
+    });
+
+  // Bridge onCardMove
+  const handleCardMove = useCallback(
+    (item: Partial<TDoc>, fromColumn: string, toColumn: string) => {
+      if (onCardMove && item.name) {
+        onCardMove(item.name, fromColumn, toColumn);
+      }
+    },
+    [onCardMove],
+  );
+
+  // Bridge onCardSelect to onCardClick
+  const handleCardSelect = useCallback(
+    (item: Partial<TDoc>, _columnId: string) => {
+      onCardClick?.(item);
+    },
+    [onCardClick],
+  );
+
+  return (
+    <Kanban
+      {...knobProps.gap}
+      columns={genericColumns}
+      renderCard={effectiveRenderCard}
+      onCardMove={handleCardMove}
+      onCardSelect={handleCardSelect}
+      isLoading={isLoading}
+      {...kanbanProps}
+    />
+  );
+}

package/src/FrappeList.stories.tsx

@@ -0,0 +1,178 @@
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { action } from "@multiplatform.one/storybook";
+import { Text, XStack, YStack } from "tamagui";
+import { FrappeList } from "./FrappeList";
+import { FrappeProvider } from "./FrappeProvider";
+
+export default {
+  title: "FrappeUI/FrappeList",
+  component: FrappeList,
+  tags: ["!test"],
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "A flexible list component connected to Frappe Live data with custom renderItem function.",
+      },
+    },
+  },
+};
+
+interface ToDo {
+  name: string;
+  doctype: string;
+  description: string;
+  status: string;
+  date: string;
+  priority: string;
+}
+
+const todoFixtures: ToDo[] = Array.from({ length: 100 }, (_, i) => ({
+  name: `TODO-${String(i + 1).padStart(3, "0")}`,
+  doctype: "ToDo",
+  description: `Task ${i + 1}: ${["Review document", "Update code", "Write tests", "Fix bug", "Deploy app"][i % 5]}`,
+  status: ["Open", "Working", "Completed"][i % 3],
+  date: `2026-01-${String((i % 28) + 1).padStart(2, "0")}`,
+  priority: ["Low", "Medium", "High"][i % 3],
+}));
+
+export const Default = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ ToDo: todoFixtures.slice(0, 10) })}
+  >
+    <FrappeList<ToDo>
+      doctype="ToDo"
+      renderItem={(doc) => (
+        <YStack gap="$0.5" paddingVertical="$2" paddingHorizontal="$3">
+          <XStack gap="$2" alignItems="center">
+            <Text fontSize="$2" color="$color10" minWidth={80}>
+              Task:
+            </Text>
+            <Text fontSize="$3">{doc.description || "-"}</Text>
+          </XStack>
+          <XStack gap="$2" alignItems="center">
+            <Text fontSize="$2" color="$color10" minWidth={80}>
+              Status:
+            </Text>
+            <Text fontSize="$3">{doc.status || "-"}</Text>
+          </XStack>
+        </YStack>
+      )}
+      onItemClick={action("onItemClick")}
+    />
+  </FrappeProvider>
+);
+Default.parameters = {
+  docs: {
+    description: {
+      story: "Basic list showing ToDo items with renderItem function.",
+    },
+  },
+};
+
+Default.storyName = "Main";
+export const WithCustomFieldRenderer = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ ToDo: todoFixtures.slice(0, 10) })}
+  >
+    <FrappeList<ToDo>
+      doctype="ToDo"
+      renderItem={(doc) => (
+        <YStack gap="$0.5" paddingVertical="$2" paddingHorizontal="$3">
+          <XStack gap="$2" alignItems="center">
+            <Text fontSize="$2" color="$color10" minWidth={80}>
+              Task:
+            </Text>
+            <Text fontSize="$3">{doc.description || "-"}</Text>
+          </XStack>
+          <XStack gap="$2" alignItems="center">
+            <Text fontSize="$2" color="$color10" minWidth={80}>
+              Status:
+            </Text>
+            <Text
+              paddingHorizontal="$2"
+              paddingVertical="$1"
+              backgroundColor={
+                doc.status === "Completed"
+                  ? "$green4"
+                  : doc.status === "Working"
+                    ? "$yellow4"
+                    : "$blue4"
+              }
+              borderRadius="$2"
+              fontSize="$2"
+            >
+              {doc.status}
+            </Text>
+          </XStack>
+          <XStack gap="$2" alignItems="center">
+            <Text fontSize="$2" color="$color10" minWidth={80}>
+              Priority:
+            </Text>
+            <Text fontSize="$3">{doc.priority || "-"}</Text>
+          </XStack>
+        </YStack>
+      )}
+      onItemClick={action("onItemClick")}
+    />
+  </FrappeProvider>
+);
+WithCustomFieldRenderer.parameters = {
+  docs: {
+    description: {
+      story: "List with custom rendering for status badges.",
+    },
+  },
+};
+
+export const VirtualScrolling = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ ToDo: todoFixtures })}
+  >
+    <FrappeList<ToDo>
+      doctype="ToDo"
+      renderItem={(doc) => (
+        <YStack gap="$0.5" paddingVertical="$2" paddingHorizontal="$3">
+          <XStack gap="$2" alignItems="center">
+            <Text fontSize="$2" color="$color10" minWidth={80}>
+              ID:
+            </Text>
+            <Text fontSize="$3">{doc.name || "-"}</Text>
+          </XStack>
+          <XStack gap="$2" alignItems="center">
+            <Text fontSize="$2" color="$color10" minWidth={80}>
+              Task:
+            </Text>
+            <Text fontSize="$3">{doc.description || "-"}</Text>
+          </XStack>
+          <XStack gap="$2" alignItems="center">
+            <Text fontSize="$2" color="$color10" minWidth={80}>
+              Status:
+            </Text>
+            <Text fontSize="$3">{doc.status || "-"}</Text>
+          </XStack>
+          <XStack gap="$2" alignItems="center">
+            <Text fontSize="$2" color="$color10" minWidth={80}>
+              Priority:
+            </Text>
+            <Text fontSize="$3">{doc.priority || "-"}</Text>
+          </XStack>
+        </YStack>
+      )}
+      height={400}
+      estimateSize={50}
+      onItemClick={action("onItemClick")}
+    />
+  </FrappeProvider>
+);
+VirtualScrolling.parameters = {
+  docs: {
+    description: {
+      story: "List with virtual scrolling for 100 items - only visible items are rendered.",
+    },
+  },
+};

package/src/FrappeList.tsx

@@ -0,0 +1,79 @@
+import { List, type ListProps } from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import type React from "react";
+import { useFrappeConfig } from "./FrappeProvider";
+import { useFrappePagination } from "./useFrappePagination";
+
+export interface FrappeListProps<TDoc extends { name: string; doctype: string }> extends Omit<
+  ListProps<Partial<TDoc>>,
+  "items" | "onLoadMore" | "hasMore" | "renderItem"
+> {
+  /** Custom render function for each item. */
+  renderItem: (item: Partial<TDoc>, index: number) => React.ReactNode;
+  baseURL?: string;
+  auth?: any;
+  syncOptions?: any;
+  doctype: string;
+  fields?: readonly (keyof TDoc & string)[];
+  filters?: Partial<TDoc> | Array<[keyof TDoc & string, string, any]>;
+  /** Page size for progressive loading (default 20). */
+  pageSize?: number;
+}
+
+/**
+ * Thin Frappe wrapper around the generic List component.
+ *
+ * Internally bridges VirtualPageManager's cursor-based pagination
+ * to the generic `onLoadMore` / `hasMore` interface via
+ * `useFrappePagination`, so consumers never deal with cursors.
+ */
+export function FrappeList<TDoc extends { name: string; doctype: string }>({
+  baseURL,
+  auth,
+  syncOptions,
+  doctype,
+  fields,
+  filters,
+  pageSize,
+  renderItem,
+  ...listProps
+}: FrappeListProps<TDoc>) {
+  const config = useFrappeConfig();
+  const { knobProps } = useResolvedKnobs();
+
+  const finalBaseURL = baseURL ?? config?.baseURL;
+  const finalAuth = auth ?? config?.auth;
+  const finalSyncOptions = syncOptions ?? config?.syncOptions;
+
+  if (!finalBaseURL) {
+    throw new Error("FrappeList requires baseURL prop or FrappeProvider with baseURL");
+  }
+
+  const connectionConfig = {
+    baseURL: finalBaseURL,
+    socketPort: config?.socketPort,
+    auth: finalAuth,
+    syncOptions: finalSyncOptions,
+    fixtures: config?.fixtures,
+  };
+
+  // Bridge VirtualPageManager pagination to generic onLoadMore/hasMore
+  const { items, isLoading, onLoadMore, hasMore } = useFrappePagination<TDoc>(
+    connectionConfig,
+    doctype,
+    { fields, filters, pageSize },
+  );
+
+  return (
+    <List
+      {...knobProps.borderRadius}
+      items={items}
+      isLoading={isLoading}
+      renderItem={renderItem}
+      onLoadMore={onLoadMore}
+      hasMore={hasMore}
+      emptyMessage={`No ${doctype} records found`}
+      {...listProps}
+    />
+  );
+}