@multiplatform.one/frappe-ui 6.0.0

package/src/FormSidebar.tsx

@@ -0,0 +1,215 @@
+/**
+ * FormSidebar — a generic sidebar for form views.
+ *
+ * Renders configurable sections (image, custom sections, metadata)
+ * from a generic section config.  Completely framework-agnostic: no
+ * dependency on Frappe, live queries, or any ORM layer.
+ */
+
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { PlusIcon, UserIcon } from "@phosphor-icons/react";
+import React from "react";
+import { useTranslation } from "react-i18next";
+import {
+  Avatar,
+  Button,
+  Image,
+  ListItem,
+  Separator,
+  Text,
+  XStack,
+  YStack,
+  type YStackProps,
+} from "tamagui";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A single item in an assignment / shared-with section. */
+export interface SidebarPerson {
+  id: string;
+  label: string;
+  sublabel?: string;
+}
+
+/** A generic sidebar section. */
+export interface SidebarSection {
+  /** Unique key for this section */
+  key: string;
+  /** Section heading */
+  title: string;
+  /** Optional icon next to the heading */
+  icon?: React.ReactNode;
+  /** Items to render in this section */
+  items?: SidebarPerson[];
+  /** Empty-state text when items is empty */
+  emptyText?: string;
+  /** Callback when the "add" button is pressed */
+  onAdd?: () => void;
+  /** Optional custom renderer – if provided, items/emptyText are ignored */
+  render?: () => React.ReactNode;
+}
+
+/** Metadata entry displayed in the Info section. */
+export interface SidebarMetadataEntry {
+  label: string;
+  icon?: React.ReactNode;
+}
+
+export interface FormSidebarProps extends Omit<YStackProps, "children"> {
+  /** Optional image URL to display at the top */
+  imageUrl?: string;
+  /** Configurable sections to render (assignments, shares, tags, etc.) */
+  sections?: SidebarSection[];
+  /** Metadata lines shown at the bottom (e.g. created by / modified by) */
+  metadata?: SidebarMetadataEntry[];
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function getInitials(name: string): string {
+  const parts = name.split(/[\s@]/);
+  if (parts.length >= 2) {
+    return (parts[0][0] + parts[1][0]).toUpperCase();
+  }
+  return name.substring(0, 2).toUpperCase();
+}
+
+const avatarColors = ["$blue4", "$green4", "$orange4", "$purple4", "$red4"];
+function avatarColor(index: number): string {
+  return avatarColors[index % avatarColors.length];
+}
+
+const textColors = ["$blue11", "$green11", "$orange11", "$purple11", "$red11"];
+function textColor(index: number): string {
+  return textColors[index % textColors.length];
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function FormSidebar({
+  imageUrl,
+  sections = [],
+  metadata = [],
+  ...stackProps
+}: FormSidebarProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+
+  return (
+    <YStack
+      {...knobProps.borderRadius}
+      {...knobProps.panelPadding}
+      {...knobProps.gapLg}
+      width={280}
+      borderRightWidth={1}
+      borderRightColor="$borderColor"
+      {...stackProps}
+    >
+      {/* -- Image section -- */}
+      {imageUrl && (
+        <>
+          <YStack alignItems="center" gap="$2">
+            <Image
+              {...knobProps.borderRadius}
+              source={{ uri: imageUrl }}
+              width={200}
+              height={200}
+              resizeMode="contain"
+            />
+          </YStack>
+          <Separator />
+        </>
+      )}
+
+      {/* -- Dynamic sections -- */}
+      {sections.map((section, sectionIdx) => (
+        <React.Fragment key={section.key}>
+          <YStack {...knobProps.gap}>
+            <XStack alignItems="center" justifyContent="space-between">
+              <Text fontSize="$2" fontWeight="600" color="$color10">
+                {section.title}
+              </Text>
+              {section.onAdd && (
+                <Button
+                  size="$1"
+                  chromeless
+                  icon={PlusIcon}
+                  aria-label={t("Add {{section}}", {
+                    section: section.title,
+                  })}
+                  onPress={section.onAdd}
+                />
+              )}
+            </XStack>
+
+            {section.render ? (
+              section.render()
+            ) : section.items && section.items.length > 0 ? (
+              <YStack {...knobProps.gap}>
+                {section.items.map((item) => (
+                  <XStack key={item.id} gap="$2" alignItems="center">
+                    <Avatar circular size="$2" backgroundColor={avatarColor(sectionIdx)}>
+                      <Avatar.Fallback backgroundColor={avatarColor(sectionIdx)}>
+                        <Text fontSize="$1" color={textColor(sectionIdx)} fontWeight="600">
+                          {getInitials(item.label)}
+                        </Text>
+                      </Avatar.Fallback>
+                    </Avatar>
+                    <YStack flex={1}>
+                      <Text fontSize="$2" color="$color12" numberOfLines={1}>
+                        {item.label}
+                      </Text>
+                      {item.sublabel && (
+                        <Text fontSize="$1" color="$color9">
+                          {item.sublabel}
+                        </Text>
+                      )}
+                    </YStack>
+                  </XStack>
+                ))}
+              </YStack>
+            ) : (
+              <Text fontSize="$1" color="$color9">
+                {section.emptyText ?? t("None")}
+              </Text>
+            )}
+          </YStack>
+
+          {sectionIdx < sections.length - 1 && <Separator />}
+        </React.Fragment>
+      ))}
+
+      {/* -- Separator before metadata -- */}
+      {metadata.length > 0 && sections.length > 0 && <Separator />}
+
+      {/* -- Info / Metadata -- */}
+      {metadata.length > 0 && (
+        <YStack gap="$1">
+          <Text fontSize="$2" fontWeight="600" color="$color10" paddingHorizontal="$2">
+            {t("Info")}
+          </Text>
+          {metadata.map((entry) => (
+            <ListItem
+              key={entry.label}
+              size={knobProps.sizeToken}
+              icon={
+                (entry.icon ?? (
+                  <UserIcon size={14} color="var(--color10)" style={{ flexShrink: 0 }} />
+                )) as any
+              }
+              title={<Text color="$color10">{entry.label}</Text>}
+              backgroundColor="transparent"
+              paddingVertical="$1"
+            />
+          ))}
+        </YStack>
+      )}
+    </YStack>
+  );
+}

package/src/FrappeCalendar.stories.tsx

@@ -0,0 +1,246 @@
+import { InMemoryFixtureProvider } from "@multiplatform.one/frappe";
+import { action } from "@multiplatform.one/storybook";
+import { Text } from "tamagui";
+import { FrappeCalendar } from "./FrappeCalendar";
+import { FrappeProvider } from "./FrappeProvider";
+
+export default {
+  title: "FrappeUI/FrappeCalendar",
+  component: FrappeCalendar,
+  tags: ["!test"],
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "A calendar component with month, week, and day views for displaying and managing events from Frappe doctypes.",
+      },
+    },
+  },
+};
+
+interface CalEvent {
+  name: string;
+  doctype: string;
+  subject: string;
+  starts_on: string;
+  ends_on: string;
+  color: string;
+  description: string;
+}
+
+const today = new Date();
+const formatDate = (date: Date) => date.toISOString().split("T")[0];
+
+const eventFixtures: CalEvent[] = [
+  {
+    name: "EVENT-001",
+    doctype: "CalEvent",
+    subject: "Team Meeting",
+    starts_on: `${formatDate(today)} 09:00:00`,
+    ends_on: `${formatDate(today)} 10:00:00`,
+    color: "#3B82F6",
+    description: "Weekly team sync",
+  },
+  {
+    name: "EVENT-002",
+    doctype: "CalEvent",
+    subject: "Client Call",
+    starts_on: `${formatDate(today)} 14:00:00`,
+    ends_on: `${formatDate(today)} 15:00:00`,
+    color: "#10B981",
+    description: "Project review with client",
+  },
+  {
+    name: "EVENT-003",
+    doctype: "CalEvent",
+    subject: "Training Session",
+    starts_on: `${formatDate(new Date(today.getTime() + 86400000))} 10:00:00`,
+    ends_on: `${formatDate(new Date(today.getTime() + 86400000))} 12:00:00`,
+    color: "#F59E0B",
+    description: "New employee onboarding",
+  },
+  {
+    name: "EVENT-004",
+    doctype: "CalEvent",
+    subject: "Product Launch",
+    starts_on: `${formatDate(new Date(today.getTime() + 172800000))} 09:00:00`,
+    ends_on: `${formatDate(new Date(today.getTime() + 172800000))} 18:00:00`,
+    color: "#8B5CF6",
+    description: "Major release event",
+  },
+  {
+    name: "EVENT-005",
+    doctype: "CalEvent",
+    subject: "Review Meeting",
+    starts_on: `${formatDate(new Date(today.getTime() + 345600000))} 15:00:00`,
+    ends_on: `${formatDate(new Date(today.getTime() + 345600000))} 16:00:00`,
+    color: "#EF4444",
+    description: "Quarterly review",
+  },
+];
+
+export const MonthView = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ CalEvent: eventFixtures })}
+  >
+    <FrappeCalendar<CalEvent>
+      doctype="CalEvent"
+      dateField="starts_on"
+      endDateField="ends_on"
+      titleField="subject"
+      descriptionField="description"
+      colorField="color"
+      defaultView="month"
+      onEventClick={action("onEventClick")}
+      onDateClick={action("onDateClick")}
+      height={600}
+    />
+  </FrappeProvider>
+);
+MonthView.parameters = {
+  docs: {
+    description: {
+      story: "Calendar in month view showing events across multiple days.",
+    },
+  },
+};
+
+MonthView.storyName = "Main";
+export const WeekView = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ CalEvent: eventFixtures })}
+  >
+    <FrappeCalendar<CalEvent>
+      doctype="CalEvent"
+      dateField="starts_on"
+      endDateField="ends_on"
+      titleField="subject"
+      colorField="color"
+      defaultView="week"
+      onEventClick={action("onEventClick")}
+      onDateClick={action("onDateClick")}
+      height={600}
+    />
+  </FrappeProvider>
+);
+WeekView.parameters = {
+  docs: {
+    description: {
+      story: "Calendar in week view for detailed scheduling.",
+    },
+  },
+};
+
+export const DayView = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ CalEvent: eventFixtures })}
+  >
+    <FrappeCalendar<CalEvent>
+      doctype="CalEvent"
+      dateField="starts_on"
+      endDateField="ends_on"
+      titleField="subject"
+      descriptionField="description"
+      colorField="color"
+      defaultView="day"
+      onEventClick={action("onEventClick")}
+      height={600}
+    />
+  </FrappeProvider>
+);
+DayView.parameters = {
+  docs: {
+    description: {
+      story: "Calendar in day view showing hour-by-hour schedule.",
+    },
+  },
+};
+
+export const WithCustomEventRenderer = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ CalEvent: eventFixtures })}
+  >
+    <FrappeCalendar<CalEvent>
+      doctype="CalEvent"
+      dateField="starts_on"
+      endDateField="ends_on"
+      titleField="subject"
+      colorField="color"
+      defaultView="month"
+      renderEvent={(event) => (
+        <>
+          <Text fontWeight="600">{event.subject}</Text>
+          <Text fontSize="$1" color="$gray11">
+            {event.description}
+          </Text>
+        </>
+      )}
+      onEventClick={action("onEventClick")}
+      height={600}
+    />
+  </FrappeProvider>
+);
+WithCustomEventRenderer.parameters = {
+  docs: {
+    description: {
+      story: "Calendar with custom event rendering showing additional details.",
+    },
+  },
+};
+
+export const MondayFirstDay = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ CalEvent: eventFixtures })}
+  >
+    <FrappeCalendar<CalEvent>
+      doctype="CalEvent"
+      dateField="starts_on"
+      endDateField="ends_on"
+      titleField="subject"
+      colorField="color"
+      defaultView="month"
+      firstDayOfWeek={1}
+      onEventClick={action("onEventClick")}
+      height={600}
+    />
+  </FrappeProvider>
+);
+MondayFirstDay.parameters = {
+  docs: {
+    description: {
+      story: "Calendar with Monday as the first day of the week.",
+    },
+  },
+};
+
+export const WithEventMove = () => (
+  <FrappeProvider
+    baseURL="https://demo.frappe.cloud"
+    fixtures={new InMemoryFixtureProvider({ CalEvent: eventFixtures })}
+  >
+    <FrappeCalendar<CalEvent>
+      doctype="CalEvent"
+      dateField="starts_on"
+      endDateField="ends_on"
+      titleField="subject"
+      colorField="color"
+      defaultView="week"
+      onEventMove={action("onEventMove")}
+      onEventClick={action("onEventClick")}
+      height={600}
+    />
+  </FrappeProvider>
+);
+WithEventMove.parameters = {
+  docs: {
+    description: {
+      story: "Calendar with drag-and-drop to reschedule events.",
+    },
+  },
+};

package/src/FrappeCalendar.tsx

@@ -0,0 +1,201 @@
+import { useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
+import { Calendar, type CalendarEvent } from "@multiplatform.one/components";
+import React, { useMemo, useCallback, type ReactNode } from "react";
+import { Spinner, Text, YStack, type YStackProps } from "tamagui";
+import { useTranslation } from "react-i18next";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useFrappeConfig } from "./FrappeProvider";
+
+export type CalendarViewType = "month" | "week" | "day";
+
+export type CalendarEventRenderer<TDoc> = (
+  event: Partial<TDoc>,
+  defaultContent: React.ReactNode,
+) => React.ReactNode;
+
+export interface FrappeCalendarProps<TDoc extends { name: string; doctype: string }> extends Omit<
+  YStackProps,
+  "children"
+> {
+  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]>;
+  dateField: keyof TDoc & string;
+  endDateField?: keyof TDoc & string;
+  titleField?: keyof TDoc & string;
+  descriptionField?: keyof TDoc & string;
+  colorField?: keyof TDoc & string;
+  defaultView?: CalendarViewType;
+  initialDate?: Date;
+  renderEvent?: CalendarEventRenderer<TDoc>;
+  onEventClick?: (event: Partial<TDoc>) => void;
+  onEventMove?: (eventName: string, fromDate: Date, toDate: Date) => void | Promise<void>;
+  onDateClick?: (date: Date) => void;
+  loading?: React.ReactNode;
+  error?: (error: Error) => React.ReactNode;
+  height?: number;
+  showNavigation?: boolean;
+  showViewSwitcher?: boolean;
+  firstDayOfWeek?: 0 | 1;
+}
+
+/**
+ * Parse a date string from Frappe (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS).
+ */
+function parseDate(dateStr: string | Date | undefined): Date | null {
+  if (!dateStr) return null;
+  if (dateStr instanceof Date) return dateStr;
+  const parsed = new Date(dateStr.replace(" ", "T"));
+  return isNaN(parsed.getTime()) ? null : parsed;
+}
+
+/**
+ * Thin Frappe wrapper around the generic Calendar component.
+ *
+ * Fetches data via `useFrappeCollection` / `useLiveQuery`, maps Frappe
+ * documents to `CalendarEvent` objects, and passes them to the generic
+ * `Calendar` from `@multiplatform.one/components`.
+ */
+export function FrappeCalendar<TDoc extends { name: string; doctype: string }>({
+  baseURL,
+  auth,
+  syncOptions,
+  doctype,
+  fields,
+  filters,
+  dateField,
+  endDateField,
+  titleField,
+  descriptionField,
+  colorField,
+  defaultView = "month",
+  initialDate,
+  renderEvent: renderEventProp,
+  onEventClick,
+  onEventMove: _onEventMove,
+  onDateClick,
+  loading,
+  error: _error,
+  height: heightProp,
+  showNavigation = true,
+  showViewSwitcher = true,
+  firstDayOfWeek = 0,
+  ...stackProps
+}: FrappeCalendarProps<TDoc>) {
+  const config = useFrappeConfig();
+  const { knobProps } = useResolvedKnobs();
+  const { t } = useTranslation();
+  const height =
+    heightProp ?? (knobProps.sizeToken === "$3" ? 480 : knobProps.sizeToken === "$5" ? 720 : 600);
+
+  const finalBaseURL = baseURL ?? config?.baseURL;
+  const finalAuth = auth ?? config?.auth;
+  const finalSyncOptions = syncOptions ?? config?.syncOptions;
+
+  if (!finalBaseURL) {
+    throw new Error("FrappeCalendar 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(dateField);
+    fieldSet.add("name" as keyof TDoc & string);
+    if (endDateField) fieldSet.add(endDateField);
+    if (titleField) fieldSet.add(titleField);
+    if (descriptionField) fieldSet.add(descriptionField);
+    if (colorField) fieldSet.add(colorField);
+    return Array.from(fieldSet) as (keyof TDoc & string)[];
+  }, [fields, dateField, endDateField, titleField, descriptionField, colorField]);
+
+  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 docs = useMemo(() => (rawData as TDoc[] | undefined) ?? [], [rawData]);
+
+  // Map Frappe documents to generic CalendarEvent objects
+  const events = useMemo((): CalendarEvent[] => {
+    return docs
+      .map((doc) => {
+        const startDate = parseDate((doc as any)[dateField]);
+        if (!startDate) return null;
+        const endDate = endDateField ? parseDate((doc as any)[endDateField]) : undefined;
+        const title = titleField ? String((doc as any)[titleField] || doc.name) : doc.name;
+        const color = colorField ? (doc as any)[colorField] : undefined;
+        return {
+          id: doc.name,
+          title,
+          start: startDate,
+          end: endDate ?? undefined,
+          color,
+          _doc: doc, // Attach original doc for callbacks
+        } as CalendarEvent;
+      })
+      .filter(Boolean) as CalendarEvent[];
+  }, [docs, dateField, endDateField, titleField, colorField]);
+
+  // Bridge renderEvent from Frappe doc to generic CalendarEvent
+  const renderEventBridge = useMemo(() => {
+    if (!renderEventProp) return undefined;
+    return (calEvent: CalendarEvent): ReactNode => {
+      const doc = (calEvent as any)._doc as TDoc;
+      return renderEventProp(doc, null);
+    };
+  }, [renderEventProp]);
+
+  // Bridge onEventClick from generic CalendarEvent to Frappe doc
+  const handleEventClick = useCallback(
+    (event: CalendarEvent) => {
+      if (onEventClick) {
+        const doc = docs.find((d) => d.name === event.id);
+        if (doc) onEventClick(doc);
+      }
+    },
+    [onEventClick, docs],
+  );
+
+  if (isLoading) {
+    if (loading) return <>{loading}</>;
+    return (
+      <YStack {...knobProps.panelPadding} alignItems="center" {...stackProps}>
+        <Spinner size="large" />
+        <Text color="$color10" marginTop="$2">
+          {t("Loading {{doctype}}...", { doctype })}
+        </Text>
+      </YStack>
+    );
+  }
+
+  return (
+    <Calendar
+      {...knobProps.borderRadius}
+      events={events}
+      onDateSelect={onDateClick}
+      onEventClick={handleEventClick}
+      renderEvent={renderEventBridge}
+      viewType={defaultView}
+      initialDate={initialDate}
+      height={height}
+      showNavigation={showNavigation}
+      showViewSwitcher={showViewSwitcher}
+      firstDayOfWeek={firstDayOfWeek}
+      {...stackProps}
+    />
+  );
+}