@multiplatform.one/frappe-ui 6.0.0

package/src/FrappeImageView.tsx

@@ -0,0 +1,360 @@
+import { useDocTypeMeta, useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
+import { ImageGrid } from "@multiplatform.one/components";
+import { ImageSquareIcon } from "@phosphor-icons/react";
+import React, { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { Card, Image, Spinner, Text, YStack, type YStackProps } from "tamagui";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useFrappeConfig } from "./FrappeProvider";
+
+/**
+ * Resolves an image field value to a full URL.
+ */
+function getImageUrl(value: unknown, baseURL: string): string {
+  if (!value || typeof value !== "string") return "";
+  if (value.startsWith("http://") || value.startsWith("https://")) return value;
+  if (value.startsWith("/")) return `${baseURL}${value}`;
+  return value;
+}
+
+export interface FrappeImageViewProps<TDoc extends { name: string; doctype: string }> extends Omit<
+  YStackProps,
+  "children"
+> {
+  doctype: string;
+  imageField?: string;
+  titleField?: string;
+  subtitleField?: string;
+  columns?: number;
+  filters?: Partial<TDoc> | Array<[keyof TDoc & string, string, any]>;
+  fields?: readonly (keyof TDoc & string)[];
+  searchText?: string;
+  onItemClick?: (doc: Partial<TDoc>) => void;
+  baseURL?: string;
+  auth?: { useToken?: boolean; token?: string; type?: string };
+  syncOptions?: Record<string, unknown>;
+  /**
+   * Items to render during server-side rendering and pre-hydration. Allows
+   * the consumer (typically a `useLoader` result) to provide initial data
+   * so the grid can render real content on the server instead of a spinner.
+   *
+   * Once the client mounts, the live `useLiveQuery` data takes over and
+   * this prop is ignored.
+   */
+  ssrItems?: TDoc[];
+}
+
+/**
+ * Thin Frappe wrapper around the generic ImageGrid component.
+ *
+ * Fetches data via `useFrappeCollection` / `useLiveQuery`, resolves image
+ * URLs, and passes items to the generic `ImageGrid` from
+ * `@multiplatform.one/components`.
+ *
+ * **SSR**: `useLiveQuery` (via `useSyncExternalStore`) lacks a
+ * `getServerSnapshot` so it can't run on the server. If the consumer
+ * passes `ssrItems` (e.g. from a route loader), we render them through
+ * the same card design as the client so the SSR markup matches the
+ * eventual hydrated output. Otherwise we fall back to a loading spinner.
+ */
+export function FrappeImageView<TDoc extends { name: string; doctype: string }>(
+  props: FrappeImageViewProps<TDoc>,
+) {
+  const { knobProps } = useResolvedKnobs();
+  const { t } = useTranslation();
+  // Note: `typeof window` is unreliable because react-native-web polyfills
+  // `window` during SSR. Use `import.meta.env.SSR` (Vite) instead.
+  if (import.meta.env.SSR) {
+    const {
+      doctype,
+      imageField,
+      titleField = "name",
+      subtitleField,
+      columns = 4,
+      onItemClick,
+      baseURL,
+      ssrItems,
+      ...stackProps
+    } = props;
+
+    if (ssrItems && ssrItems.length > 0 && imageField && baseURL) {
+      return (
+        <ImageGrid
+          items={ssrItems}
+          columns={columns}
+          onItemClick={onItemClick}
+          emptyMessage={t("No items found")}
+          testID={`${doctype.toLowerCase()}-list`}
+          {...(stackProps as any)}
+          renderItem={(doc) => (
+            <FrappeImageCard
+              doc={doc as Record<string, unknown>}
+              doctype={doctype}
+              imageField={imageField}
+              titleField={titleField}
+              subtitleField={subtitleField}
+              baseURL={baseURL}
+              onItemClick={onItemClick as ((doc: Partial<unknown>) => void) | undefined}
+              knobProps={knobProps}
+            />
+          )}
+        />
+      );
+    }
+
+    return (
+      <YStack
+        {...knobProps.panelPadding}
+        alignItems="center"
+        justifyContent="center"
+        {...(stackProps as any)}
+      >
+        <Spinner size="large" />
+        <Text color="$color10" marginTop="$2">
+          {t("Loading {{doctype}}...", { doctype })}
+        </Text>
+      </YStack>
+    );
+  }
+
+  // Avoid explicit generic <TDoc> in JSX — the `one` compiler injects
+  // data-one-source attributes that break generic syntax.  TypeScript
+  // infers TDoc from the props.
+  return <FrappeImageViewClient {...props} />;
+}
+
+/**
+ * Inner client-only implementation that calls the hooks requiring a
+ * browser environment (useFrappeCollection, useLiveQuery).
+ */
+function FrappeImageViewClient<TDoc extends { name: string; doctype: string }>({
+  doctype,
+  imageField,
+  titleField,
+  subtitleField,
+  columns = 4,
+  filters,
+  fields,
+  searchText,
+  onItemClick,
+  baseURL,
+  auth,
+  syncOptions,
+  ...stackProps
+}: FrappeImageViewProps<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("FrappeImageView requires baseURL prop or FrappeProvider with baseURL");
+  }
+
+  // Memoize so downstream hooks (useDocTypeMeta / useFrappeCollection) receive
+  // a stable config reference across renders instead of a fresh object each
+  // time (which would otherwise retrigger their effects every render).
+  const appConfig = useMemo(
+    () => ({
+      baseURL: finalBaseURL,
+      socketPort: config?.socketPort,
+      auth: finalAuth,
+      syncOptions: finalSyncOptions,
+      fixtures: config?.fixtures,
+    }),
+    [finalBaseURL, config?.socketPort, finalAuth, finalSyncOptions, config?.fixtures],
+  );
+
+  const { meta, isLoading: isMetaLoading } = useDocTypeMeta(appConfig, doctype);
+
+  const effectiveImageField = imageField ?? meta?.image_field;
+  const effectiveTitleField = titleField ?? meta?.title_field ?? "name";
+
+  const effectiveFields = useMemo(() => {
+    const fieldSet = new Set<string>(fields as string[] | undefined);
+    fieldSet.add("name");
+    if (effectiveImageField) fieldSet.add(effectiveImageField);
+    if (effectiveTitleField) fieldSet.add(effectiveTitleField);
+    if (subtitleField) fieldSet.add(subtitleField);
+    return Array.from(fieldSet) as (keyof TDoc & string)[];
+  }, [fields, effectiveImageField, effectiveTitleField, subtitleField]);
+
+  const effectiveFilters = useMemo(() => {
+    if (!searchText || !effectiveTitleField) return filters;
+    const searchFilter: Array<[string, string, any]> = [
+      [effectiveTitleField, "like", `%${searchText}%`],
+    ];
+    if (Array.isArray(filters)) {
+      return [
+        ...(filters as Array<[string, string, any]>),
+        ...searchFilter,
+      ] as unknown as typeof filters;
+    }
+    if (filters) {
+      const objectFilters = Object.entries(filters).map(
+        ([key, value]) => [key, "=", value] as [string, string, any],
+      );
+      return [...objectFilters, ...searchFilter] as unknown as typeof filters;
+    }
+    return searchFilter as unknown as typeof filters;
+  }, [filters, searchText, effectiveTitleField]);
+
+  const collection = useFrappeCollection<TDoc>(appConfig, doctype, {
+    fields: effectiveFields,
+    filters: effectiveFilters,
+  });
+  const { data: rawData, isLoading: isDataLoading } = useLiveQuery(
+    (q) => (collection ? q.from({ _list: collection }) : null),
+    [collection],
+  );
+  const items = useMemo(() => (rawData as TDoc[] | undefined) ?? [], [rawData]);
+
+  // Only block rendering on DocType-meta loading when we actually need it
+  // (i.e. the caller didn't pass explicit image/title fields). The meta
+  // endpoint is permission-gated and 403s for Guests; when the fields are
+  // already known, the grid can render from Guest-readable list data without
+  // it. Always wait on the actual list data.
+  const needsMeta = !imageField || !titleField;
+  // Loading state
+  if ((needsMeta && isMetaLoading) || isDataLoading) {
+    return (
+      <YStack
+        {...knobProps.panelPadding}
+        alignItems="center"
+        justifyContent="center"
+        {...stackProps}
+      >
+        <Spinner size="large" />
+        <Text color="$color10" marginTop="$2">
+          {t("Loading {{doctype}}...", { doctype })}
+        </Text>
+      </YStack>
+    );
+  }
+
+  // No image field configured
+  if (!effectiveImageField) {
+    return (
+      <YStack {...knobProps.panelPadding} alignItems="center" {...knobProps.gap} {...stackProps}>
+        <ImageSquareIcon size={48} color="$color8" />
+        <Text color="$color10">{t("No image field configured for {{doctype}}", { doctype })}</Text>
+      </YStack>
+    );
+  }
+
+  return (
+    <ImageGrid
+      items={items}
+      columns={columns}
+      onItemClick={onItemClick}
+      emptyMessage={t("No items found")}
+      testID={`${doctype.toLowerCase()}-list`}
+      {...(stackProps as any)}
+      renderItem={(doc) => (
+        <FrappeImageCard
+          doc={doc as Record<string, unknown>}
+          doctype={doctype}
+          imageField={effectiveImageField}
+          titleField={effectiveTitleField}
+          subtitleField={subtitleField}
+          baseURL={finalBaseURL}
+          onItemClick={onItemClick as ((doc: Partial<unknown>) => void) | undefined}
+          knobProps={knobProps}
+        />
+      )}
+    />
+  );
+}
+
+/**
+ * Card renderer shared between SSR and client paths so they produce
+ * matching markup (avoiding hydration mismatches) and the look stays
+ * defined in one place.
+ */
+function FrappeImageCard({
+  doc,
+  doctype,
+  imageField,
+  titleField,
+  subtitleField,
+  baseURL,
+  onItemClick,
+  knobProps,
+}: {
+  doc: Record<string, unknown>;
+  doctype: string;
+  imageField: string;
+  titleField: string;
+  subtitleField?: string;
+  baseURL: string;
+  onItemClick?: (doc: Partial<unknown>) => void;
+  knobProps: ReturnType<typeof useResolvedKnobs>["knobProps"];
+}) {
+  const imageUrl = getImageUrl(doc[imageField], baseURL);
+  const title = doc[titleField] || doc.name;
+  const subtitle = subtitleField ? doc[subtitleField] : undefined;
+  const imageHeight = knobProps.sizeToken === "$3" ? 140 : knobProps.sizeToken === "$5" ? 220 : 180;
+  const footerPaddingTop =
+    knobProps.sizeToken === "$3" ? 150 : knobProps.sizeToken === "$5" ? 230 : 190;
+
+  return (
+    <Card
+      testID={`${doctype.toLowerCase()}-card-${doc.name}`}
+      size={knobProps.sizeToken}
+      elevation={knobProps.elevation}
+      borderWidth={1}
+      borderColor="$borderColor"
+      overflow="hidden"
+      cursor="pointer"
+      hoverStyle={{ scale: 0.98, borderColor: "$accentBackground" }}
+      pressStyle={{ scale: 0.97 }}
+      onPress={(e) => {
+        // Bind click directly to `doc` so the correct item is used even
+        // if the ImageGrid wrapper's closure captured a stale/recycled item.
+        (e as unknown as { stopPropagation?: () => void })?.stopPropagation?.();
+        onItemClick?.(doc as Partial<unknown>);
+      }}
+    >
+      <Card.Background>
+        {imageUrl ? (
+          <Image src={imageUrl} width="100%" height={imageHeight} objectFit="cover" />
+        ) : (
+          <YStack
+            width="100%"
+            height={imageHeight}
+            backgroundColor="$color2"
+            alignItems="center"
+            justifyContent="center"
+          >
+            <ImageSquareIcon size={48} color="$color8" />
+          </YStack>
+        )}
+      </Card.Background>
+      <Card.Footer {...knobProps.panelPadding} paddingTop={footerPaddingTop}>
+        <YStack gap="$1">
+          <Text
+            testID={`${doctype.toLowerCase()}-name-${doc.name}`}
+            fontWeight="600"
+            fontSize={knobProps.sizeToken}
+            numberOfLines={1}
+          >
+            {String(title)}
+          </Text>
+          {subtitle != null && (
+            <Text
+              testID={`${doctype.toLowerCase()}-subtitle-${doc.name}`}
+              color="$color10"
+              fontSize="$2"
+              numberOfLines={1}
+            >
+              {String(subtitle)}
+            </Text>
+          )}
+        </YStack>
+      </Card.Footer>
+    </Card>
+  );
+}

package/src/FrappeKanban.stories.tsx

@@ -0,0 +1,172 @@
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { action } from "@multiplatform.one/storybook";
+import { FrappeKanban, type KanbanColumn } from "./FrappeKanban";
+import { FrappeProvider } from "./FrappeProvider";
+
+export default {
+  title: "FrappeUI/FrappeKanban",
+  component: FrappeKanban,
+  tags: ["!test"],
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "A drag-and-drop Kanban board component for Frappe doctypes with real-time updates.",
+      },
+    },
+  },
+};
+
+interface ToDo {
+  name: string;
+  doctype: string;
+  description: string;
+  status: string;
+}
+
+const todoFixtures: ToDo[] = [
+  { name: "TODO-001", doctype: "ToDo", description: "Review documentation", status: "Open" },
+  { name: "TODO-002", doctype: "ToDo", description: "Fix login bug", status: "Open" },
+  { name: "TODO-003", doctype: "ToDo", description: "Update dependencies", status: "Working" },
+  { name: "TODO-004", doctype: "ToDo", description: "Write unit tests", status: "Working" },
+  { name: "TODO-005", doctype: "ToDo", description: "Deploy to staging", status: "Pending Review" },
+  { name: "TODO-006", doctype: "ToDo", description: "Merge PR #42", status: "Completed" },
+];
+
+const todoColumns: KanbanColumn[] = [
+  { value: "Open", title: "To Do", color: "#6366F1" },
+  { value: "Working", title: "In Progress", color: "#F59E0B" },
+  { value: "Pending Review", title: "Review", color: "#8B5CF6" },
+  { value: "Completed", title: "Done", color: "#10B981" },
+];
+
+export const Default = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ ToDo: todoFixtures })}
+  >
+    <FrappeKanban<ToDo>
+      doctype="ToDo"
+      columns={todoColumns}
+      statusField="status"
+      titleField="description"
+      onCardClick={action("onCardClick")}
+      onCardMove={action("onCardMove")}
+      minColumnHeight={500}
+    />
+  </FrappeProvider>
+);
+Default.parameters = {
+  docs: {
+    description: {
+      story: "Basic Kanban board connected to a Frappe ToDo doctype.",
+    },
+  },
+};
+
+Default.storyName = "Main";
+export const WithCardCreation = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ ToDo: todoFixtures })}
+  >
+    <FrappeKanban<ToDo>
+      doctype="ToDo"
+      columns={todoColumns}
+      statusField="status"
+      titleField="description"
+      enableCardCreation
+      onCardClick={action("onCardClick")}
+      onCardMove={action("onCardMove")}
+      onCreateCard={action("onCreateCard")}
+      minColumnHeight={500}
+    />
+  </FrappeProvider>
+);
+WithCardCreation.parameters = {
+  docs: {
+    description: {
+      story: "Kanban board with add card buttons on each column.",
+    },
+  },
+};
+
+interface Bug {
+  name: string;
+  doctype: string;
+  title: string;
+  severity: string;
+  status: string;
+}
+
+const bugFixtures: Bug[] = [
+  {
+    name: "BUG-001",
+    doctype: "Bug",
+    title: "Login not working on Safari",
+    severity: "Critical",
+    status: "New",
+  },
+  {
+    name: "BUG-002",
+    doctype: "Bug",
+    title: "Page layout broken on mobile",
+    severity: "High",
+    status: "Confirmed",
+  },
+  {
+    name: "BUG-003",
+    doctype: "Bug",
+    title: "Dashboard loading slowly",
+    severity: "Medium",
+    status: "In Progress",
+  },
+  {
+    name: "BUG-004",
+    doctype: "Bug",
+    title: "Email notifications delayed",
+    severity: "Low",
+    status: "Testing",
+  },
+  {
+    name: "BUG-005",
+    doctype: "Bug",
+    title: "Fixed typo in footer",
+    severity: "Low",
+    status: "Closed",
+  },
+];
+
+const bugColumns: KanbanColumn[] = [
+  { value: "New", title: "New", color: "#EF4444" },
+  { value: "Confirmed", title: "Confirmed", color: "#F97316" },
+  { value: "In Progress", title: "In Progress", color: "#3B82F6" },
+  { value: "Testing", title: "Testing", color: "#8B5CF6" },
+  { value: "Closed", title: "Closed", color: "#22C55E" },
+];
+
+export const BugTracker = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ Bug: bugFixtures })}
+  >
+    <FrappeKanban<Bug>
+      doctype="Bug"
+      columns={bugColumns}
+      statusField="status"
+      titleField="title"
+      descriptionField="severity"
+      onCardClick={action("onCardClick")}
+      onCardMove={action("onCardMove")}
+      minColumnHeight={500}
+    />
+  </FrappeProvider>
+);
+BugTracker.parameters = {
+  docs: {
+    description: {
+      story: "Example of a bug tracking Kanban board with different columns.",
+    },
+  },
+};