@multiplatform.one/backoffice 6.4.2 → 6.6.0

package/src/form/FormTimeline.tsx

@@ -0,0 +1,577 @@
+// Contract: activity feed under the form — new-comment box, comments,
+// versions/edits, communications, assignment/attachment/like logs (desk
+// parity). Self-contained: fetches docinfo via shared/useDocinfo. Keep
+// props stable — form-core imports this.
+//
+// Composition: the generic Timeline from @multiplatform.one/components
+// supplies the composer + feed shell; every entry renders through a
+// renderEntry override for desk parity (own-comment edit/delete, version
+// "changed value of…" gray rows, communication blocks, one-line logs).
+// Mutations go through the probed desk RPCs:
+//   frappe.desk.form.utils.add_comment    { reference_doctype,
+//     reference_name, content, comment_email, comment_by } (all required)
+//   frappe.desk.form.utils.update_comment { name, content }
+//   frappe.client.delete                  { doctype: "Comment", name }
+import {
+  Avatar,
+  Button,
+  H4,
+  Spinner,
+  Tabs,
+  Text,
+  Timeline,
+  XStack,
+  YStack,
+  type TabsItem,
+  type TimelineEntry,
+} from "@multiplatform.one/components";
+import { TextArea } from "@multiplatform.one/forms";
+import { useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import { formatAbsoluteDateTime, useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  EnvelopeSimpleIcon,
+  HeartIcon,
+  InfoIcon,
+  PaperclipIcon,
+  PencilSimpleIcon,
+  RobotIcon,
+  TrashIcon,
+  UserPlusIcon,
+} from "@phosphor-icons/react";
+import { useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { invalidateDocinfo, useDocinfo } from "../shared/useDocinfo";
+import { useFrappeApp } from "../shared/useFrappeApp";
+import {
+  buildTimelineFeed,
+  filterTimelineFeed,
+  versionSummary,
+  type TimelineDocinfoLike,
+  type TimelineFeedEntry,
+  type TimelineFilterValue,
+} from "./timeline-entries";
+import {
+  formatRelativeTime,
+  htmlToText,
+  textToCommentHtml,
+  truncateText,
+  useSessionUser,
+} from "./timeline-utils";
+
+/** Feed entries shown before the "Load older" collapse kicks in. */
+const PAGE_SIZE = 20;
+
+export interface FormTimelineProps {
+  doctype: string;
+  name: string;
+  /**
+   * Prefetched docinfo from the composing form screen (or a story fixture).
+   * When the composer owns docinfo (this or `refreshDocInfo` is provided)
+   * the timeline renders it and skips its own fetch.
+   */
+  docInfo?: TimelineDocinfoLike;
+  /** Composer-owned docinfo refresh, called after comment mutations. */
+  refreshDocInfo?: () => void;
+  /** Session user when already known (skips the get_logged_user lookup). */
+  currentUser?: string;
+  /** Frappe connection; `baseURL` resolves relative avatar image paths. */
+  connection?: { baseURL?: string };
+}
+
+interface EditingState {
+  /** Comment docname being edited */
+  docname: string;
+  text: string;
+}
+
+export function FormTimeline({
+  doctype,
+  name,
+  docInfo,
+  refreshDocInfo,
+  currentUser,
+  connection,
+}: FormTimelineProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const app = useFrappeApp();
+  const config = useFrappeConfig();
+  const { knobProps } = useResolvedKnobs();
+  const radiusToken = knobProps.borderRadius.borderRadius;
+
+  // Composed mode: the form screen (or story fixture) owns docinfo. The
+  // timeline stays self-contained otherwise via shared/useDocinfo.
+  const composed = docInfo !== undefined || refreshDocInfo !== undefined;
+  const {
+    docinfo: fetched,
+    loading,
+    error,
+    reload,
+  } = useDocinfo(composed ? undefined : doctype, composed ? undefined : name);
+  const docinfo: TimelineDocinfoLike | undefined = docInfo ?? fetched;
+  const fetchedSessionUser = useSessionUser(!currentUser);
+  const sessionUser = currentUser ?? fetchedSessionUser;
+
+  const [filter, setFilter] = useState<TimelineFilterValue>("all");
+  const [visibleCount, setVisibleCount] = useState(PAGE_SIZE);
+  const [editing, setEditing] = useState<EditingState | null>(null);
+  const [confirmingDelete, setConfirmingDelete] = useState<string | null>(null);
+  const [busyDocname, setBusyDocname] = useState<string | null>(null);
+  const [actionError, setActionError] = useState<string | undefined>(undefined);
+
+  useEffect(() => {
+    setVisibleCount(PAGE_SIZE);
+    setEditing(null);
+    setConfirmingDelete(null);
+    setActionError(undefined);
+  }, [doctype, name]);
+
+  const refresh = useCallback(() => {
+    // Keep the shared docinfo cache honest for sibling panels, then refresh
+    // whichever pipeline owns this timeline's data.
+    invalidateDocinfo(doctype, name);
+    if (refreshDocInfo) refreshDocInfo();
+    else reload();
+  }, [doctype, name, refreshDocInfo, reload]);
+
+  const reportActionError = useCallback((err: unknown, fallback: string) => {
+    const message = err instanceof Error && err.message ? String(err.message) : "";
+    const readable = htmlToText(message);
+    setActionError(readable ? truncateText(readable, 200) : fallback);
+  }, []);
+
+  const baseURL = connection?.baseURL ?? config?.baseURL;
+  const entries = useMemo(
+    () => buildTimelineFeed(docinfo, { userInfo: docinfo?.user_info, baseURL }),
+    [docinfo, baseURL],
+  );
+  const filtered = useMemo(() => filterTimelineFeed(entries, filter), [entries, filter]);
+  const visible = useMemo(() => filtered.slice(0, visibleCount), [filtered, visibleCount]);
+  const hiddenCount = Math.max(0, filtered.length - visible.length);
+
+  const handleFilterChange = useCallback((value: string) => {
+    setFilter(value as TimelineFilterValue);
+    setVisibleCount(PAGE_SIZE);
+  }, []);
+
+  // ── mutations ────────────────────────────────────────────────────────────
+
+  // Composed/fixture mode keeps the composer visible; without an app the
+  // handlers no-op (stories demo the UI, mutations need a bench).
+  const canComment = Boolean(sessionUser && (app || composed));
+
+  const handleAddComment = useCallback(
+    (content: string) => {
+      const text = content.trim();
+      if (!app || !sessionUser || !text) return;
+      const rawFullname = docinfo?.user_info?.[sessionUser]?.fullname;
+      const fullname = typeof rawFullname === "string" && rawFullname ? rawFullname : sessionUser;
+      setActionError(undefined);
+      app
+        .call()
+        .post("frappe.desk.form.utils.add_comment", {
+          reference_doctype: doctype,
+          reference_name: name,
+          content: textToCommentHtml(text),
+          comment_email: sessionUser,
+          comment_by: fullname,
+        })
+        .then(() => refresh())
+        .catch((err: unknown) => {
+          reportActionError(err, t("timeline.addFailed", "Could not add comment"));
+        });
+    },
+    [app, sessionUser, docinfo, doctype, name, refresh, reportActionError, t],
+  );
+
+  const handleSaveEdit = useCallback(() => {
+    if (!editing) return;
+    const text = editing.text.trim();
+    if (!app || !text) {
+      setEditing(null);
+      return;
+    }
+    const target = editing.docname;
+    setBusyDocname(target);
+    setActionError(undefined);
+    app
+      .call()
+      .post("frappe.desk.form.utils.update_comment", {
+        name: target,
+        content: textToCommentHtml(text),
+      })
+      .then(() => {
+        setEditing(null);
+        refresh();
+      })
+      .catch((err: unknown) => {
+        reportActionError(err, t("timeline.updateFailed", "Could not update comment"));
+      })
+      .finally(() => setBusyDocname(null));
+  }, [app, editing, refresh, reportActionError, t]);
+
+  const handleDeleteComment = useCallback(
+    (docname: string) => {
+      if (!app) {
+        setConfirmingDelete(null);
+        return;
+      }
+      setBusyDocname(docname);
+      setActionError(undefined);
+      app
+        .call()
+        .post("frappe.client.delete", { doctype: "Comment", name: docname })
+        .then(() => refresh())
+        .catch((err: unknown) => {
+          reportActionError(err, t("timeline.deleteFailed", "Could not delete comment"));
+        })
+        .finally(() => {
+          setBusyDocname(null);
+          setConfirmingDelete(null);
+        });
+    },
+    [app, refresh, reportActionError, t],
+  );
+
+  // ── entry renderers (desk parity) ────────────────────────────────────────
+
+  const renderTimestamp = (entry: TimelineFeedEntry, fontSize = "$2") => {
+    const absolute = formatAbsoluteDateTime(entry.timestamp);
+    return (
+      <Text
+        fontSize={fontSize}
+        color="$color10"
+        {...({ title: absolute } as Record<string, unknown>)}
+        aria-label={absolute}
+      >
+        {formatRelativeTime(entry.timestamp)}
+      </Text>
+    );
+  };
+
+  const displayNameOf = (entry: TimelineFeedEntry) => entry.authorName?.trim() || entry.author;
+
+  const renderCommentRow = (entry: TimelineFeedEntry) => {
+    const displayName = displayNameOf(entry);
+    const own = Boolean(sessionUser && entry.ownerId === sessionUser);
+    const isEditing = editing?.docname === entry.docname;
+    const isConfirming = confirmingDelete === entry.docname;
+    const isBusy = busyDocname === entry.docname;
+    return (
+      <XStack
+        role="article"
+        aria-label={`${displayName}, ${formatRelativeTime(entry.timestamp)}`}
+        gap="$3"
+        alignItems="flex-start"
+      >
+        <Avatar
+          circular={false}
+          borderRadius={radiusToken}
+          size="$2"
+          name={displayName}
+          src={entry.image}
+          fallbackBackgroundColor="$accentBackground"
+        />
+        <YStack flex={1} gap="$1">
+          <XStack gap="$2" alignItems="center">
+            <XStack flex={1} gap="$2" alignItems="center" flexWrap="wrap">
+              <Text fontSize="$3" fontWeight="600">
+                {displayName}
+              </Text>
+              {renderTimestamp(entry)}
+            </XStack>
+            {own && !isEditing && !isConfirming && (
+              <XStack gap="$1">
+                <Button
+                  chromeless
+                  size="$1"
+                  borderRadius={radiusToken}
+                  icon={<PencilSimpleIcon size={12} />}
+                  aria-label={t("timeline.editComment", "Edit comment")}
+                  disabled={isBusy}
+                  onPress={() => {
+                    setConfirmingDelete(null);
+                    setEditing({
+                      docname: entry.docname,
+                      text: htmlToText(entry.html ?? entry.content ?? ""),
+                    });
+                  }}
+                />
+                <Button
+                  chromeless
+                  size="$1"
+                  borderRadius={radiusToken}
+                  icon={<TrashIcon size={12} />}
+                  aria-label={t("timeline.deleteComment", "Delete comment")}
+                  disabled={isBusy}
+                  onPress={() => {
+                    setEditing(null);
+                    setConfirmingDelete(entry.docname);
+                  }}
+                />
+              </XStack>
+            )}
+          </XStack>
+          {isEditing ? (
+            <YStack gap="$2">
+              <TextArea
+                value={editing?.text ?? ""}
+                onChangeText={(text) => setEditing((prev) => (prev ? { ...prev, text } : prev))}
+                size="$3"
+                minRows={2}
+                textAreaProps={{
+                  "aria-label": t("timeline.editComment", "Edit comment"),
+                  autoFocus: true,
+                }}
+              />
+              <XStack gap="$2" justifyContent="flex-end">
+                <Button
+                  size="$2"
+                  variant="outlined"
+                  borderRadius={radiusToken}
+                  disabled={isBusy}
+                  onPress={() => setEditing(null)}
+                >
+                  {t("timeline.cancel", "Cancel")}
+                </Button>
+                <Button
+                  size="$2"
+                  borderRadius={radiusToken}
+                  disabled={!(editing?.text ?? "").trim() || isBusy}
+                  icon={isBusy ? <Spinner size="small" /> : undefined}
+                  onPress={handleSaveEdit}
+                >
+                  {t("timeline.save", "Save")}
+                </Button>
+              </XStack>
+            </YStack>
+          ) : entry.content ? (
+            <Text fontSize="$3" whiteSpace="pre-wrap">
+              {entry.content}
+            </Text>
+          ) : null}
+          {isConfirming && !isEditing && (
+            <XStack gap="$2" alignItems="center" flexWrap="wrap">
+              <Text fontSize="$2" color="$color10">
+                {t("timeline.deleteConfirm", "Delete this comment?")}
+              </Text>
+              <Button
+                size="$2"
+                theme="error"
+                borderRadius={radiusToken}
+                disabled={isBusy}
+                icon={isBusy ? <Spinner size="small" /> : undefined}
+                onPress={() => handleDeleteComment(entry.docname)}
+              >
+                {t("timeline.delete", "Delete")}
+              </Button>
+              <Button
+                chromeless
+                size="$2"
+                borderRadius={radiusToken}
+                disabled={isBusy}
+                onPress={() => setConfirmingDelete(null)}
+              >
+                {t("timeline.cancel", "Cancel")}
+              </Button>
+            </XStack>
+          )}
+        </YStack>
+      </XStack>
+    );
+  };
+
+  const renderSystemRow = (entry: TimelineFeedEntry, icon: ReactNode, text: string) => {
+    const displayName = displayNameOf(entry);
+    return (
+      <XStack
+        role="article"
+        aria-label={`${displayName} ${text}`.trim()}
+        gap="$3"
+        alignItems="flex-start"
+      >
+        <YStack width={24} height={24} alignItems="center" justifyContent="center" opacity={0.6}>
+          {icon}
+        </YStack>
+        <XStack flex={1} gap="$1.5" alignItems="center" flexWrap="wrap" paddingTop={2}>
+          <Text fontSize="$2" fontWeight="600" color="$color10">
+            {displayName}
+          </Text>
+          {text ? (
+            <Text fontSize="$2" color="$color10">
+              {text}
+            </Text>
+          ) : null}
+          <Text fontSize="$2" color="$color10" opacity={0.75}>
+            {"·"}
+          </Text>
+          {renderTimestamp(entry)}
+        </XStack>
+      </XStack>
+    );
+  };
+
+  const renderCommunicationRow = (entry: TimelineFeedEntry) => {
+    const displayName = displayNameOf(entry);
+    const icon =
+      entry.kind === "automated" ? <RobotIcon size={14} /> : <EnvelopeSimpleIcon size={14} />;
+    return (
+      <XStack
+        role="article"
+        aria-label={`${displayName}, ${entry.subject ?? ""}`.trim()}
+        gap="$3"
+        alignItems="flex-start"
+      >
+        <YStack width={24} height={24} alignItems="center" justifyContent="center" opacity={0.6}>
+          {icon}
+        </YStack>
+        <YStack
+          flex={1}
+          gap="$1"
+          borderWidth={1}
+          borderColor="$borderColor"
+          borderRadius={radiusToken}
+          padding="$3"
+        >
+          <XStack gap="$2" alignItems="center" flexWrap="wrap">
+            <Text fontSize="$3" fontWeight="600">
+              {displayName}
+            </Text>
+            {entry.author !== displayName && (
+              <Text fontSize="$2" color="$color10">
+                {entry.author}
+              </Text>
+            )}
+            {renderTimestamp(entry)}
+          </XStack>
+          {entry.subject ? (
+            <Text fontSize="$3" fontWeight="600">
+              {entry.subject}
+            </Text>
+          ) : null}
+          {entry.content ? (
+            <Text fontSize="$2" color="$color11" numberOfLines={3}>
+              {entry.content}
+            </Text>
+          ) : null}
+        </YStack>
+      </XStack>
+    );
+  };
+
+  const renderFeedEntry = (raw: TimelineEntry): ReactNode => {
+    const entry = raw as TimelineFeedEntry;
+    switch (entry.kind) {
+      case "comment":
+        return renderCommentRow(entry);
+      case "version":
+        return renderSystemRow(
+          entry,
+          <PencilSimpleIcon size={14} />,
+          entry.version
+            ? versionSummary(entry.version, (key, options) => t(key, options))
+            : t("timeline.madeChanges", "made changes"),
+        );
+      case "communication":
+      case "automated":
+        return renderCommunicationRow(entry);
+      case "assignment":
+        return renderSystemRow(entry, <UserPlusIcon size={14} />, entry.content ?? "");
+      case "attachment":
+        return renderSystemRow(entry, <PaperclipIcon size={14} />, entry.content ?? "");
+      case "like":
+        return renderSystemRow(entry, <HeartIcon size={14} />, entry.content ?? "");
+      default:
+        return renderSystemRow(entry, <InfoIcon size={14} />, entry.content ?? "");
+    }
+  };
+
+  // ── layout ───────────────────────────────────────────────────────────────
+
+  const tabItems = useMemo<TabsItem[]>(
+    () => [
+      { value: "all", label: t("timeline.filterAll", "All") },
+      { value: "comments", label: t("timeline.filterComments", "Comments") },
+      { value: "edits", label: t("timeline.filterEdits", "Edits") },
+    ],
+    [t],
+  );
+
+  const emptyLabel =
+    filter === "comments"
+      ? t("timeline.noComments", "No comments yet")
+      : filter === "edits"
+        ? t("timeline.noEdits", "No edits yet")
+        : t("timeline.noActivity", "No activity yet");
+
+  if (!docinfo) {
+    if (!composed && error && !loading) {
+      return (
+        <YStack gap="$3">
+          <H4>{t("timeline.activity", "Activity")}</H4>
+          <YStack gap="$2" alignItems="flex-start">
+            <Text fontSize="$2" color="$red10">
+              {t("timeline.loadFailed", "Could not load activity")}
+            </Text>
+            <Button size="$2" borderRadius={radiusToken} onPress={refresh}>
+              {t("timeline.retry", "Retry")}
+            </Button>
+          </YStack>
+        </YStack>
+      );
+    }
+    // Self-fetch in flight, or composed mode waiting on the parent's docinfo
+    return (
+      <YStack gap="$3">
+        <H4>{t("timeline.activity", "Activity")}</H4>
+        <XStack gap="$2" alignItems="center" justifyContent="center" padding="$4">
+          <Spinner size="small" />
+          <Text fontSize="$2" color="$color10">
+            {t("timeline.loading", "Loading activity…")}
+          </Text>
+        </XStack>
+      </YStack>
+    );
+  }
+
+  return (
+    <YStack gap="$3">
+      <H4>{t("timeline.activity", "Activity")}</H4>
+      <Tabs items={tabItems} value={filter} onChange={handleFilterChange} />
+      {actionError ? (
+        <Text fontSize="$2" color="$red10" role="alert">
+          {actionError}
+        </Text>
+      ) : null}
+      <Timeline
+        entries={visible}
+        enableAddComment={canComment}
+        onCommentAdded={canComment ? handleAddComment : undefined}
+        renderEntry={(entry) => renderFeedEntry(entry)}
+        placeholder={t("timeline.addCommentPlaceholder", "Add a comment…")}
+        labels={{
+          noActivity: emptyLabel,
+          addComment: t("timeline.addComment", "Add Comment"),
+          cancel: t("timeline.cancel", "Cancel"),
+          comment: t("timeline.comment", "Comment"),
+          sending: t("timeline.sending", "Sending…"),
+        }}
+      />
+      {hiddenCount > 0 && (
+        <XStack justifyContent="center">
+          <Button
+            chromeless
+            size="$2"
+            borderRadius={radiusToken}
+            onPress={() => setVisibleCount((count) => count + PAGE_SIZE)}
+          >
+            {t("timeline.loadOlder", {
+              defaultValue: "Load older ({{hidden}} more)",
+              hidden: hiddenCount,
+            })}
+          </Button>
+        </XStack>
+      )}
+    </YStack>
+  );
+}