@multiplatform.one/frappe-ui 6.0.0

package/src/components/timeline.tsx

@@ -0,0 +1,226 @@
+import {
+  Timeline as BaseTimeline,
+  type TimelineEntry,
+  type TimelineProps,
+  type VersionChange,
+} from "@multiplatform.one/components";
+import { useFrappeCollection, useLiveQuery } from "@multiplatform.one/frappe";
+import { useCallback, useMemo } from "react";
+import { useFrappeConfig } from "../FrappeProvider";
+
+export interface FrappeComment {
+  name: string;
+  doctype: string;
+  comment_type: string;
+  content?: string;
+  comment_by?: string;
+  comment_email?: string;
+  reference_doctype?: string;
+  reference_name?: string;
+  creation?: string;
+  modified?: string;
+  owner?: string;
+}
+
+export interface FrappeVersion {
+  name: string;
+  doctype: string;
+  docname?: string;
+  ref_doctype?: string;
+  data?: string;
+  creation?: string;
+  modified?: string;
+  owner?: string;
+}
+
+export interface FrappeTimelineProps extends Omit<TimelineProps, "entries"> {
+  doctype: string;
+  docname: string;
+  onAddComment?: (content: string) => void;
+  /** Filter entry types shown in the timeline (default: true) */
+  showComments?: boolean;
+  showVersions?: boolean;
+  showAttachments?: boolean;
+  showAssignments?: boolean;
+}
+
+function commentTypeToEntryType(commentType: string): TimelineEntry["type"] {
+  switch (commentType) {
+    case "Comment":
+      return "comment";
+    case "Attachment":
+      return "attachment";
+    case "Assignment":
+      return "assignment";
+    case "Info":
+      return "info";
+    default:
+      return "comment";
+  }
+}
+
+function frappeCommentToEntry(comment: FrappeComment): TimelineEntry {
+  return {
+    id: comment.name,
+    type: commentTypeToEntryType(comment.comment_type),
+    content: comment.content,
+    author: comment.comment_by ?? comment.owner ?? "unknown",
+    authorEmail: comment.comment_email,
+    timestamp: comment.creation ?? new Date().toISOString(),
+  };
+}
+
+function frappeVersionToEntry(version: FrappeVersion): TimelineEntry {
+  let changes: VersionChange[] | undefined;
+  if (version.data) {
+    try {
+      const parsed = JSON.parse(version.data) as {
+        changed?: Array<[string, unknown, unknown]>;
+        added?: Array<[string, unknown]>;
+        removed?: Array<[string, unknown]>;
+      };
+      changes = [
+        ...(parsed.changed ?? []).map(([field, old, next]) => ({ field, old, new: next })),
+        ...(parsed.added ?? []).map(([field, next]) => ({ field, old: undefined, new: next })),
+        ...(parsed.removed ?? []).map(([field, old]) => ({ field, old, new: undefined })),
+      ];
+    } catch {
+      // ignore malformed data
+    }
+  }
+  return {
+    id: version.name,
+    type: "version",
+    author: version.owner ?? "unknown",
+    timestamp: version.creation ?? new Date().toISOString(),
+    changes,
+  };
+}
+
+function formatRelativeTime(timestamp: string): string {
+  try {
+    const diffMs = Date.now() - new Date(timestamp).getTime();
+    const diffSeconds = Math.round(diffMs / 1000);
+    if (diffSeconds < 60) return "just now";
+    if (diffSeconds < 3600) {
+      const m = Math.round(diffSeconds / 60);
+      return `${m} minute${m !== 1 ? "s" : ""} ago`;
+    }
+    if (diffSeconds < 86400) {
+      const h = Math.round(diffSeconds / 3600);
+      return `${h} hour${h !== 1 ? "s" : ""} ago`;
+    }
+    if (diffSeconds < 2592000) {
+      const d = Math.round(diffSeconds / 86400);
+      return `${d} day${d !== 1 ? "s" : ""} ago`;
+    }
+    const mo = Math.round(diffSeconds / 2592000);
+    return `${mo} month${mo !== 1 ? "s" : ""} ago`;
+  } catch {
+    return timestamp;
+  }
+}
+
+export function Timeline({
+  doctype,
+  docname,
+  onAddComment,
+  showComments = true,
+  showVersions = true,
+  showAttachments = true,
+  showAssignments = true,
+  ...props
+}: FrappeTimelineProps) {
+  const config = useFrappeConfig();
+
+  const connectionConfig = config
+    ? { baseURL: config.baseURL, auth: config.auth, fixtures: config.fixtures }
+    : undefined;
+
+  const commentFilters = useMemo<Array<[string, string, unknown]>>(
+    () => [
+      ["reference_doctype", "=", doctype],
+      ["reference_name", "=", docname],
+    ],
+    [doctype, docname],
+  );
+
+  const versionFilters = useMemo<Array<[string, string, unknown]>>(
+    () => [
+      ["ref_doctype", "=", doctype],
+      ["docname", "=", docname],
+    ],
+    [doctype, docname],
+  );
+
+  const commentCollection = useFrappeCollection<FrappeComment>(connectionConfig, "Comment", {
+    filters: commentFilters,
+    fields: [
+      "name",
+      "comment_type",
+      "content",
+      "comment_by",
+      "comment_email",
+      "reference_doctype",
+      "reference_name",
+      "creation",
+      "modified",
+      "owner",
+    ],
+  });
+
+  const versionCollection = useFrappeCollection<FrappeVersion>(connectionConfig, "Version", {
+    filters: versionFilters,
+    fields: ["name", "docname", "ref_doctype", "data", "creation", "modified", "owner"],
+  });
+
+  const { data: commentsData } = useLiveQuery(
+    (q) => (commentCollection ? q.from({ _list: commentCollection }) : null),
+    [commentCollection],
+  );
+
+  const { data: versionsData } = useLiveQuery(
+    (q) => (versionCollection ? q.from({ _list: versionCollection }) : null),
+    [versionCollection],
+  );
+
+  const entries = useMemo<TimelineEntry[]>(() => {
+    const commentEntries = ((commentsData as FrappeComment[] | undefined) ?? [])
+      .map(frappeCommentToEntry)
+      .filter((e) => {
+        if (e.type === "comment" && !showComments) return false;
+        if (e.type === "attachment" && !showAttachments) return false;
+        if (e.type === "assignment" && !showAssignments) return false;
+        return true;
+      });
+    const versionEntries = showVersions
+      ? ((versionsData as FrappeVersion[] | undefined) ?? []).map(frappeVersionToEntry)
+      : [];
+    return [...commentEntries, ...versionEntries].sort(
+      (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime(),
+    );
+  }, [commentsData, versionsData, showComments, showVersions, showAttachments, showAssignments]);
+
+  const handleAddComment = useCallback(
+    (content: string) => {
+      onAddComment?.(content);
+    },
+    [onAddComment],
+  );
+
+  // Provide a default formatTimestamp using relative time if not explicitly passed
+  const { formatTimestamp = formatRelativeTime, enableAddComment, ...restProps } = props;
+
+  // Always provide onCommentAdded when comment input is enabled so the button renders
+  const effectiveEnableAddComment = enableAddComment !== false;
+
+  return (
+    <BaseTimeline
+      entries={entries}
+      onCommentAdded={effectiveEnableAddComment ? handleAddComment : undefined}
+      enableAddComment={effectiveEnableAddComment}
+      formatTimestamp={formatTimestamp}
+      {...restProps}
+    />
+  );
+}

package/src/desk/DeskFormPage.tsx

@@ -0,0 +1,114 @@
+/**
+ * DeskFormPage - Page component for Frappe Desk form views.
+ *
+ * Wraps FrappeForm inside DeskShell with breadcrumbs, sidebar, and timeline.
+ * Supports both create mode (no name / name === "new") and edit mode.
+ * Accepts `doctype` and `name` as props (route files read params and pass them).
+ */
+
+import React, { useEffect } from "react";
+import { useTranslation } from "react-i18next";
+import { Text, YStack } from "tamagui";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { DeskShell } from "./DeskShell";
+import { FrappeForm } from "../FrappeForm";
+import { addToRecent } from "./DeskSidebar";
+import type { BreadcrumbItem } from "@multiplatform.one/components";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface DeskFormPageProps {
+  /** DocType slug from route params (e.g. "pokemon", "poke-type") */
+  doctype: string;
+  /** Document name. If not provided or "new", renders in create mode */
+  name?: string;
+  /** Navigation handler — called when the user clicks a link */
+  onNavigate?: (path: string) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a URL slug to a display name.
+ * "pokemon" → "Pokemon", "poke-type" → "Poke Type"
+ */
+function toDisplayName(slug: string): string {
+  return slug.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function DeskFormPage({ doctype, name, onNavigate }: DeskFormPageProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+  const isCreate = !name || name === "new";
+  const displayName = toDisplayName(doctype);
+
+  // Track recent visits for edit mode
+  useEffect(() => {
+    if (!isCreate && name) {
+      addToRecent({
+        label: `${displayName}: ${name}`,
+        path: `/desk/${doctype}/${name}`,
+      });
+    }
+  }, [doctype, name, displayName, isCreate]);
+
+  if (!doctype) {
+    return (
+      <YStack
+        flex={1}
+        alignItems="center"
+        justifyContent="center"
+        {...knobProps.panelPadding}
+        {...knobProps.borderRadius}
+        {...knobProps.gap}
+      >
+        <Text color="$color10" fontSize={knobProps.sizeToken} {...knobProps.body}>
+          {t("No DocType specified")}
+        </Text>
+      </YStack>
+    );
+  }
+
+  const breadcrumbs: BreadcrumbItem[] = [
+    { label: t("Desk"), href: "/desk" },
+    { label: displayName, href: `/desk/${doctype}` },
+    { label: isCreate ? t("New") : (name ?? "") },
+  ];
+
+  const handleNavigate = (path: string) => {
+    onNavigate?.(path);
+  };
+
+  return (
+    <DeskShell
+      breadcrumbs={breadcrumbs}
+      onNavigate={handleNavigate}
+      activePath={`/desk/${doctype}/${name || "new"}`}
+    >
+      <YStack flex={1} {...knobProps.gap} {...knobProps.borderRadius} {...knobProps.surface}>
+        <FrappeForm
+          doctype={displayName}
+          name={isCreate ? undefined : name}
+          showToolbar
+          showSidebar
+          showTimeline
+          onSave={(doc) => {
+            if (isCreate && doc.name) {
+              handleNavigate(`/desk/${doctype}/${doc.name}`);
+            }
+          }}
+          onCancel={() => handleNavigate(`/desk/${doctype}`)}
+          onDelete={() => handleNavigate(`/desk/${doctype}`)}
+        />
+      </YStack>
+    </DeskShell>
+  );
+}

package/src/desk/DeskListPage.tsx

@@ -0,0 +1,104 @@
+/**
+ * DeskListPage - Page component for Frappe Desk list views.
+ *
+ * Wraps FrappeListView inside DeskShell with breadcrumbs and navigation.
+ * Accepts `doctype` as a prop (route files read params and pass them through).
+ */
+
+import React from "react";
+import { useTranslation } from "react-i18next";
+import { Text, YStack } from "tamagui";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { DeskShell } from "./DeskShell";
+import { FrappeListView } from "../FrappeListView";
+import { addToRecent } from "./DeskSidebar";
+import type { BreadcrumbItem } from "@multiplatform.one/components";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface DeskListPageProps {
+  /** DocType slug from route params (e.g. "pokemon", "poke-type") */
+  doctype: string;
+  /** Navigation handler — called when the user clicks a link */
+  onNavigate?: (path: string) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a URL slug to a display name.
+ * "pokemon" → "Pokemon", "poke-type" → "Poke Type"
+ */
+function toDisplayName(slug: string): string {
+  return slug.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function DeskListPage({ doctype, onNavigate }: DeskListPageProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+
+  if (!doctype) {
+    return (
+      <YStack
+        flex={1}
+        alignItems="center"
+        justifyContent="center"
+        {...knobProps.panelPadding}
+        {...knobProps.borderRadius}
+        {...knobProps.gap}
+      >
+        <Text color="$color10" fontSize={knobProps.sizeToken} {...knobProps.body}>
+          {t("No DocType specified")}
+        </Text>
+      </YStack>
+    );
+  }
+
+  const displayName = toDisplayName(doctype);
+
+  const breadcrumbs: BreadcrumbItem[] = [
+    { label: t("Desk"), href: "/desk" },
+    { label: displayName },
+  ];
+
+  const handleNavigate = (path: string) => {
+    onNavigate?.(path);
+  };
+
+  const handleItemClick = (doc: Partial<{ name: string; doctype: string }>) => {
+    if (!doc.name) return;
+    const path = `/desk/${doctype}/${doc.name}`;
+    addToRecent({ label: `${displayName}: ${doc.name}`, path });
+    handleNavigate(path);
+  };
+
+  const handleAdd = () => {
+    handleNavigate(`/desk/${doctype}/new`);
+  };
+
+  return (
+    <DeskShell
+      breadcrumbs={breadcrumbs}
+      onNavigate={handleNavigate}
+      activePath={`/desk/${doctype}`}
+    >
+      <YStack flex={1} {...knobProps.gap} {...knobProps.borderRadius}>
+        <FrappeListView
+          doctype={displayName}
+          onItemClick={handleItemClick}
+          onAdd={handleAdd}
+          showToolbar
+          enableViewSwitcher
+        />
+      </YStack>
+    </DeskShell>
+  );
+}

package/src/desk/DeskShell.tsx

@@ -0,0 +1,123 @@
+/**
+ * DeskShell - Top-level layout component for Frappe Desk.
+ *
+ * Composes the Awesomebar (top), DeskSidebar (left), Breadcrumbs,
+ * and a main content area into a full-page desk layout.
+ *
+ * Uses semantic HTML elements via Tamagui's `tag` prop for accessibility:
+ * - Header for the top bar
+ * - Nav for the sidebar
+ * - Main for the content area
+ */
+
+import { useHotkey } from "@tanstack/react-hotkeys";
+import type React from "react";
+import { useTranslation } from "react-i18next";
+import { Text, XStack, YStack } from "tamagui";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { Awesomebar } from "./awesomebar";
+import { Breadcrumbs, type BreadcrumbItem } from "@multiplatform.one/components";
+import { DeskSidebar } from "./DeskSidebar";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface DeskShellProps {
+  children: React.ReactNode;
+  /** Breadcrumb items */
+  breadcrumbs?: BreadcrumbItem[];
+  /** Navigation handler */
+  onNavigate?: (path: string) => void;
+  /** Current path for sidebar active state */
+  activePath?: string;
+  /** Show sidebar (default true) */
+  showSidebar?: boolean;
+  /** Show awesomebar (default true) */
+  showAwesomebar?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+export function DeskShell({
+  children,
+  breadcrumbs,
+  onNavigate,
+  activePath,
+  showSidebar = true,
+  showAwesomebar = true,
+}: DeskShellProps) {
+  const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs();
+
+  // Desk-level keyboard shortcuts via @tanstack/react-hotkeys
+  useHotkey(
+    "Mod+K",
+    () => {
+      const input = document.querySelector<HTMLInputElement>("[data-awesomebar-input]");
+      if (input) input.focus();
+    },
+    { enabled: showAwesomebar, conflictBehavior: "allow" },
+  );
+
+  useHotkey(
+    "Escape",
+    () => {
+      if (document.activeElement instanceof HTMLElement) {
+        document.activeElement.blur();
+      }
+    },
+    { conflictBehavior: "allow" },
+  );
+
+  return (
+    <YStack flex={1} height="100%">
+      {/* Header with Awesomebar */}
+      {showAwesomebar && (
+        <XStack
+          role="banner"
+          {...knobProps.surface}
+          height={knobProps.sizeToken === "$5" ? "$7" : knobProps.sizeToken === "$3" ? "$5" : "$6"}
+          alignItems="center"
+          paddingHorizontal="$4"
+          borderBottomWidth={1}
+          borderBottomColor="$borderColor"
+        >
+          <Text
+            fontSize={knobProps.sizeToken}
+            marginRight="$4"
+            {...knobProps.heading}
+            fontWeight="700"
+          >
+            {t("Desk")}
+          </Text>
+          <Awesomebar onNavigate={onNavigate} flex={1} />
+        </XStack>
+      )}
+
+      <XStack flex={1}>
+        {/* Nav sidebar */}
+        {showSidebar && (
+          <YStack role="navigation">
+            <DeskSidebar onNavigate={onNavigate} activePath={activePath} />
+          </YStack>
+        )}
+
+        {/* Main content */}
+        <YStack role="main" flex={1}>
+          {/* Breadcrumbs */}
+          {breadcrumbs && breadcrumbs.length > 0 && (
+            <Breadcrumbs items={breadcrumbs} onNavigate={onNavigate} />
+          )}
+
+          {/* Content */}
+          <YStack flex={1} overflow="scroll">
+            {children}
+          </YStack>
+        </YStack>
+      </XStack>
+    </YStack>
+  );
+}