@lark-apaas/coding-template-nestjs-react-fullstack 0.1.59 → 0.1.60-alpha.20261105085132

package/template/client/src/components/business-ui/record-comments/internal/suggestions.tsx

@@ -0,0 +1,456 @@
+import type { CommentDataSource, MentionKind, MentionOption } from '../types';
+import { mentionKey, safeUrl, COMMENT_THEME_CLASS } from './model';
+import * as React from 'react';
+import { useEffect, useRef, useState, useLayoutEffect } from 'react';
+import { cn } from '@/lib/utils';
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
+import { DocumentIcon } from './icons';
+import { LoaderCircle } from 'lucide-react';
+import { autoUpdate } from '@floating-ui/dom';
+import { createPortal } from 'react-dom';
+
+interface Result {
+  key: string;
+  sessionKey: string;
+  painted: boolean;
+  items: MentionOption[];
+  nextCursor?: string;
+  loading: boolean;
+  error?: string;
+}
+export function useMentionSearch(
+  source: CommentDataSource,
+  session: { id: number; query: string } | null,
+  kind: MentionKind,
+) {
+  const key = JSON.stringify([
+    source.scopeKey,
+    session?.id,
+    session?.query,
+    kind,
+  ]);
+  const sessionKey = JSON.stringify([source.scopeKey, session?.id, kind]);
+  const [state, setState] = useState<Result>({
+    key: '',
+    sessionKey: '',
+    painted: false,
+    items: [],
+    loading: false,
+  });
+  const controller = useRef<AbortController | null>(null);
+  const currentKey = useRef(key);
+  currentKey.current = key;
+  const runRef = useRef<(cursor?: string) => void>(() => {});
+  useEffect(() => {
+    const abort = new AbortController();
+    controller.current = abort;
+    let pending = false;
+    const run = async (cursor?: string) => {
+      if (!session || pending) return;
+      pending = true;
+      setState((previous) => ({
+        key,
+        sessionKey,
+        painted: previous.sessionKey === sessionKey && previous.painted,
+        items: previous.sessionKey === sessionKey ? previous.items : [],
+        loading: true,
+      }));
+      try {
+        const args = { kind, cursor, signal: abort.signal };
+        const result =
+          !session.query && source.recommend
+            ? await source.recommend(args)
+            : await source.search({ ...args, query: session.query });
+        if (abort.signal.aborted || currentKey.current !== key) return;
+        setState((previous) => {
+          const unique = new Map(
+            (cursor ? previous.items : []).map((item) => [
+              mentionKey(item.ref),
+              item,
+            ]),
+          );
+          for (const item of result.items)
+            unique.set(mentionKey(item.ref), item);
+          return {
+            key,
+            sessionKey,
+            painted: true,
+            items: [...unique.values()],
+            nextCursor: result.nextCursor,
+            loading: false,
+          };
+        });
+      } catch (error) {
+        if (!abort.signal.aborted && currentKey.current === key)
+          setState((previous) => ({
+            ...previous,
+            key,
+            sessionKey,
+            painted: true,
+            items: cursor ? previous.items : [],
+            loading: false,
+            error: error instanceof Error ? error.message : '搜索失败，请重试',
+            nextCursor: cursor,
+          }));
+      } finally {
+        pending = false;
+      }
+    };
+    runRef.current = (cursor) => {
+      void run(cursor);
+    };
+    const timer = session
+      ? setTimeout(
+          () => {
+            void run();
+          },
+          session.query ? 200 : 0,
+        )
+      : undefined;
+    return () => {
+      clearTimeout(timer);
+      abort.abort();
+    };
+  }, [source, key, sessionKey]);
+  const result =
+    state.key === key
+      ? state
+      : {
+          key,
+          sessionKey,
+          painted: state.sessionKey === sessionKey && state.painted,
+          items: state.sessionKey === sessionKey ? state.items : [],
+          loading: Boolean(session),
+        };
+  return {
+    ...result,
+    initialLoading: result.loading && !result.painted,
+    loadMore: () => runRef.current(result.nextCursor),
+    retry: () => runRef.current(),
+  };
+}
+
+function HighlightedLabel({ label, query }: { label: string; query: string }) {
+  if (!query) return <>{label}</>;
+  const parts: React.ReactNode[] = [];
+  let start = 0;
+  const lower = label.toLocaleLowerCase();
+  const needle = query.toLocaleLowerCase();
+  for (
+    let index = lower.indexOf(needle);
+    index >= 0;
+    index = lower.indexOf(needle, start)
+  ) {
+    parts.push(label.slice(start, index));
+    parts.push(
+      <span key={index} className="text-primary">
+        {label.slice(index, index + query.length)}
+      </span>,
+    );
+    start = index + query.length;
+  }
+  parts.push(label.slice(start));
+  return <>{parts}</>;
+}
+
+type Props = {
+  container?: HTMLElement;
+  anchor: () => DOMRect | null;
+  editorElement: HTMLElement;
+  id: string;
+  items: MentionOption[];
+  selected: number;
+  query?: string;
+  onSelect: (item: MentionOption) => void;
+  onHover: (index: number) => void;
+  loading: boolean;
+  initialLoading?: boolean;
+  error?: string;
+  retry: () => void;
+  loadMore: () => void;
+  hasMore: boolean;
+};
+
+/** UD SkeletonMention: 4 × 280/40 SVGs, 32px circle, 70/200 × 14 text, left 16px. */
+function MentionSkeleton() {
+  const gradient = React.useId().replace(/:/g, '');
+  return (
+    <div
+      className="replica-comment-mention-skeleton"
+      role="status"
+      aria-label="正在加载推荐人员"
+    >
+      {[0, 1, 2, 3].map((row) => (
+        <svg
+          key={row}
+          width="280"
+          height="40"
+          viewBox="0 0 280 40"
+          aria-hidden="true"
+        >
+          <defs>
+            <linearGradient id={`${gradient}-${row}`}>
+              <stop offset="0%" stopColor="var(--muted)" />
+              <stop offset="50%" stopColor="var(--muted)" stopOpacity=".7" />
+              <stop offset="100%" stopColor="var(--muted)" />
+            </linearGradient>
+          </defs>
+          <g fill={`url(#${gradient}-${row})`}>
+            <circle cx="16" cy="16" r="16" />
+            <rect x="40" y="0" rx="6" width="70" height="14" />
+            <rect x="40" y="20" rx="6" width="200" height="14" />
+          </g>
+        </svg>
+      ))}
+    </div>
+  );
+}
+
+/** Source: miaoda biz-mention/position + UD MentionPanel and OptionItem less. */
+export function MentionSuggestions({
+  container: providedContainer,
+  anchor,
+  editorElement,
+  id,
+  items,
+  selected,
+  query = '',
+  onSelect,
+  onHover,
+  loading,
+  initialLoading: loadingInitial,
+  error,
+  retry,
+  loadMore,
+  hasMore,
+}: Props) {
+  // Stay inside the editor's modal boundary so its focus scope and pointer
+  // guard treat a candidate click as an interaction within that modal.
+  const container =
+    providedContainer ||
+    editorElement.closest<HTMLElement>('[role="dialog"], [role="alertdialog"]') ||
+    document.body;
+  const panel = React.useRef<HTMLDivElement>(null);
+  const list = React.useRef<HTMLDivElement>(null);
+  const initialLoading = loadingInitial ?? (loading && !items.length);
+  const [showMask, setShowMask] = React.useState(false);
+  useEffect(() => {
+    setShowMask(false);
+    if (!loading || initialLoading) return;
+    const timer = setTimeout(() => setShowMask(true), 300);
+    return () => clearTimeout(timer);
+  }, [loading, initialLoading, query]);
+  useLayoutEffect(() => {
+    const element = panel.current;
+    if (!element) return;
+    const reference = {
+      contextElement: editorElement,
+      getBoundingClientRect: () =>
+        anchor() || editorElement.getBoundingClientRect(),
+    };
+    const update = () => {
+      const rect = reference.getBoundingClientRect();
+      const viewport = document.documentElement;
+      const screenWidth = viewport.clientWidth || window.innerWidth;
+      const screenHeight = viewport.clientHeight || window.innerHeight;
+      const bounds =
+        container && container !== document.body
+          ? container.getBoundingClientRect()
+          : null;
+      const topEdge = Math.max(0, bounds?.top || 0);
+      const bottomEdge = Math.min(screenHeight, bounds?.bottom ?? screenHeight);
+      const leftEdge = Math.max(0, bounds?.left || 0);
+      const rightEdge = Math.min(screenWidth, bounds?.right ?? screenWidth);
+      const below = bottomEdge - rect.bottom;
+      const above = rect.top - topEdge;
+      const up = below < 431 && (above >= 431 || above > below);
+      const maxHeight = Math.min(417, Math.max(0, (up ? above : below) - 14));
+      const boxWidth = Math.min(360, Math.max(0, rightEdge - leftEdge - 24));
+      element.style.width = `${boxWidth}px`;
+      const height = Math.min(
+        Math.max(64, (list.current?.scrollHeight || 0) + 2),
+        maxHeight,
+      );
+      const preferLeft =
+        rightEdge - rect.left < 372 && rect.right - leftEdge >= 372;
+      Object.assign(element.style, {
+        left: `${Math.max(leftEdge + 12, Math.min(preferLeft ? rect.right - boxWidth : rect.left, rightEdge - boxWidth - 12))}px`,
+        top: `${up ? Math.max(topEdge + 12, rect.top - height - 2) : rect.bottom + 2}px`,
+        height: `${height}px`,
+        minHeight: `${Math.min(64, maxHeight)}px`,
+        visibility: 'visible',
+      });
+    };
+    const stop = autoUpdate(reference, element, update);
+    const observer =
+      typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(update);
+    if (list.current) observer?.observe(list.current);
+    return () => {
+      stop();
+      observer?.disconnect();
+    };
+  }, [
+    anchor,
+    editorElement,
+    container,
+    items,
+    initialLoading,
+    error,
+    hasMore,
+    query,
+  ]);
+  useLayoutEffect(() => {
+    list.current
+      ?.querySelector('[aria-selected="true"]')
+      ?.scrollIntoView({ block: 'nearest' });
+  }, [selected, items]);
+  return createPortal(
+    <div
+      ref={panel}
+      data-replica-comment-suggestions
+      data-loading={loading || undefined}
+      className={cn(COMMENT_THEME_CLASS, 'replica-comment-mention-panel')}
+      style={{
+        visibility: 'hidden',
+        width: 360,
+        minHeight: 64,
+        maxHeight: 417,
+      }}
+      onPointerDown={(event) => event.preventDefault()}
+      onWheel={(event) => event.stopPropagation()}
+    >
+      <span className="sr-only" role="status">
+        {loading ? '正在搜索' : `${items.length} 个结果`}
+      </span>
+      <div className="replica-comment-mention-list-container">
+        <div
+          ref={list}
+          id={id}
+          role="listbox"
+          aria-label="提及搜索结果"
+          aria-busy={loading}
+          className="replica-comment-mention-list"
+          onScroll={(event) => {
+            const element = event.currentTarget;
+            if (
+              hasMore &&
+              !loading &&
+              !error &&
+              element.scrollHeight - element.scrollTop - element.clientHeight <
+                32
+            )
+              loadMore();
+          }}
+        >
+          {initialLoading ? (
+            <MentionSkeleton />
+          ) : (
+            items.map((item, index) => (
+              <div
+                key={mentionKey(item.ref)}
+                id={`${id}-${index}`}
+                role="option"
+                aria-selected={selected === index}
+                aria-disabled={loading || undefined}
+                className="replica-comment-mention-option-container"
+                onPointerMove={() => {
+                  if (!loading && selected !== index) onHover(index);
+                }}
+                onClick={() => {
+                  if (!loading) onSelect(item);
+                }}
+              >
+                <div className="replica-comment-mention-option">
+                  <div className="replica-comment-mention-avatar">
+                    {item.ref.kind === 'user' ? (
+                      <Avatar className="size-8 shrink-0">
+                        <AvatarImage src={safeUrl(item.avatarUrl)} alt="" />
+                        <AvatarFallback className="bg-primary text-sm text-primary-foreground">
+                          {Array.from(item.label.trim())[0] || '@'}
+                        </AvatarFallback>
+                      </Avatar>
+                    ) : (
+                      <DocumentIcon
+                        refValue={item.ref}
+                        metadata={item.document}
+                        variant="option"
+                      />
+                    )}
+                  </div>
+                  <div className="replica-comment-mention-main">
+                    <div className="replica-comment-mention-title">
+                      <span
+                        className="replica-comment-mention-title-content"
+                        title={item.label}
+                      >
+                        <HighlightedLabel label={item.label} query={query} />
+                      </span>
+                      {item.isExternal ? (
+                        <span className="shrink-0 rounded-[2px] border border-border px-1 text-xs text-[var(--subtle-foreground)]">
+                          外部
+                        </span>
+                      ) : null}
+                    </div>
+                    {item.description ? (
+                      <div
+                        className="replica-comment-mention-subtitle"
+                        title={item.description}
+                      >
+                        <HighlightedLabel
+                          label={item.description}
+                          query={query}
+                        />
+                      </div>
+                    ) : null}
+                  </div>
+                </div>
+              </div>
+            ))
+          )}
+          {!items.length && !loading && !error ? (
+            <div role="status" className="replica-comment-mention-text">
+              没有匹配结果，换个关键词试试吧
+            </div>
+          ) : null}
+          {error ? (
+            <div role="alert" className="replica-comment-mention-text">
+              <button
+                type="button"
+                disabled={loading}
+                onClick={retry}
+                className="inline text-left"
+                title="点击重新加载"
+              >
+                <svg
+                  aria-hidden="true"
+                  viewBox="0 0 24 24"
+                  className="mr-2 inline-block size-[1em] align-[-0.14em] text-[var(--comment-warning)]"
+                >
+                  <path
+                    fill="currentColor"
+                    d="M23 12c0 6.075-4.925 11-11 11S1 18.075 1 12 5.925 1 12 1s11 4.925 11 11ZM12 7a1 1 0 0 0-1 1v5a1 1 0 1 0 2 0V8a1 1 0 0 0-1-1Zm0 8a1 1 0 1 0 0 2 1 1 0 0 0 0-2Z"
+                  />
+                </svg>
+                加载失败，请检查网络后重试
+              </button>
+            </div>
+          ) : null}
+          {hasMore && !initialLoading && !error ? (
+            <span className="sr-only" role="status">
+              {loading ? '正在加载…' : '向下滚动加载更多'}
+            </span>
+          ) : null}
+        </div>
+        {showMask && loading ? (
+          <div className="replica-comment-mention-loading-mask">
+            <LoaderCircle
+              aria-label="正在搜索"
+              className="size-5 animate-spin text-primary"
+            />
+          </div>
+        ) : null}
+      </div>
+    </div>,
+    container || document.body,
+  );
+}

package/template/client/src/components/business-ui/record-comments/internal/view-types.ts

@@ -0,0 +1,84 @@
+import type { CommentReaction } from './reactions';
+import type { CommentDataSource, CommentMentionClickHandler, CommentValue, MentionRef } from '../types';
+import type { LocalCommentMutation } from './mutations';
+import type { ReactNode } from 'react';
+
+export interface DiscussionImage {
+  id: string;
+  url: string;
+  name: string;
+  file?: File;
+  width?: number;
+  height?: number;
+}
+export interface DiscussionReply {
+  /** Internal UI state; never part of the server comment protocol. */
+  mutation?: LocalCommentMutation;
+  mutationBlocked?: boolean;
+  replyID: string;
+  author: MentionRef | null;
+  link?: string;
+  /** Explicit capabilities supplied by the host/backend, independent of display names. */
+  permissions?: { canReact?: boolean; canEdit: boolean; canDelete: boolean; canCopyLink: boolean };
+  createTime: number;
+  /** Last confirmed edit in this component session, in Unix seconds. */
+  updateTime?: number;
+  value: CommentValue;
+  private?: boolean;
+  edited?: boolean;
+  images: DiscussionImage[];
+  reactions: CommentReaction[];
+}
+export interface DiscussionThread {
+  commentID: string;
+  creator: MentionRef | null;
+  createTime: number;
+  isSolved: boolean;
+  /** First reply is the comment body; all subsequent replies share this discussion. */
+  replies: DiscussionReply[];
+}
+export interface DiscussionDraft {
+  commentID?: string;
+  value: CommentValue;
+  images: DiscussionImage[];
+  private: boolean;
+}
+export interface DiscussionPanelProps {
+  source: CommentDataSource;
+  currentUser?: MentionRef;
+  /** IDs belonging to the same signed-in person, e.g. their Lark and Miaoda IDs. */
+  currentUserAliases?: readonly string[];
+  /** Optional reference-viewer highlights when comparing a captured thread. */
+  highlightUserIDs?: readonly string[];
+  comments: readonly DiscussionThread[];
+  onSubmit: (draft: DiscussionDraft) => Promise<void> | void;
+  onEdit: (
+    commentID: string,
+    replyID: string,
+    value: CommentValue,
+    images: DiscussionImage[],
+  ) => Promise<void> | void;
+  onDelete: (commentID: string, replyID?: string) => Promise<void> | void;
+  onToggleReaction: (commentID: string, replyID: string, key: string) => Promise<void> | void;
+  /** Optional controlled-panel integration; legacy previews keep their defaults. */
+  allowCompose?: boolean;
+  optimisticMutations?: boolean;
+  onRetryMutation?: (id: string) => void;
+  allowReact?: boolean;
+  showReactions?: boolean;
+  enableImages?: boolean;
+  enableEditImages?: boolean;
+  enablePrivateComments?: boolean;
+  autoScrollNewReplies?: boolean;
+  listHeader?: ReactNode;
+  listFooter?: ReactNode;
+  emptyState?: ReactNode;
+  loadReactionDetails?: (commentID: string, replyID: string, signal: AbortSignal) => Promise<readonly CommentReaction[]>;
+  onMentionClick?: CommentMentionClickHandler;
+  resolveUserRef?: (id: string) => MentionRef;
+  getCommentLink?: (commentID: string, reply: DiscussionReply) => string;
+  enableDocuments?: boolean;
+  className?: string;
+  submittedReplyID?: string;
+  onScrolledToReply?: () => void;
+}

package/template/client/src/components/business-ui/record-comments/types.ts

@@ -0,0 +1,118 @@
+import type { Ref } from 'react';
+
+export type MentionRef =
+  | { kind: 'user'; id: string; idType: 'apaas-user' | 'lark-user' | 'snapshot' }
+  | { kind: 'document'; id: string; resourceType: string };
+
+export interface MentionOption {
+  ref: MentionRef;
+  label: string;
+  avatarUrl?: string;
+  href?: string;
+  description?: string;
+  document?: DocumentMentionMetadata;
+  isExternal?: boolean;
+  /** Known host-document embed permission; a grey link still opens the access-request page. */
+  readable?: boolean;
+}
+
+export interface DocumentMentionMetadata {
+  subType?: number;
+  iconInfo?: string;
+}
+
+export type MentionResult =
+  | (MentionOption & { status: 'resolved' })
+  | { ref: MentionRef; status: 'not-found' | 'forbidden' | 'error' };
+
+export type CommentPart =
+  | { type: 'text'; text: string }
+  | { type: 'break' }
+  | { type: 'link'; url: string }
+  | { type: 'unresolved-mention' }
+  | {
+      type: 'mention';
+      ref: MentionRef;
+      label?: string;
+      href?: string;
+      document?: DocumentMentionMetadata;
+    };
+
+/** A host supplies authenticated document search and metadata, independently of user IDs. */
+export type CommentDocumentSource = Pick<
+  CommentDataSource,
+  'scopeKey' | 'search' | 'resolve' | 'recommend'
+>;
+
+export interface CommentValue {
+  version: 1;
+  content: CommentPart[];
+}
+
+/** Confirmed reply.content protocol. Editor metadata is not part of the request. */
+export type CommentApiContent =
+  | { type: 'text'; text: string }
+  | { type: 'mention'; userID?: number | null }
+  | { type: 'link'; url: string };
+
+export interface CommentSubmitPayload {
+  content: CommentApiContent[];
+}
+
+export type MentionKind = 'all' | 'user' | 'document';
+
+/** Keep this object stable. Change scopeKey when the user/tenant/app/permissions change. */
+export interface CommentDataSource {
+  scopeKey: string;
+  /** Bare @ default list, independent of keyword search. Failures must reject. */
+  recommend?: (args: {
+    kind: MentionKind;
+    cursor?: string;
+    signal: AbortSignal;
+  }) => Promise<{ items: MentionOption[]; nextCursor?: string }>;
+  /** Legacy sources without recommend can still handle an empty query here. */
+  search(args: {
+    query: string;
+    kind: MentionKind;
+    cursor?: string;
+    signal: AbortSignal;
+  }): Promise<{ items: MentionOption[]; nextCursor?: string }>;
+  resolve(refs: MentionRef[], signal: AbortSignal): Promise<MentionResult[]>;
+}
+
+export interface CommentInputProps {
+  ref?: Ref<CommentInputHandle>;
+  documentKey: string;
+  value: CommentValue;
+  /** Synchronously set the controlled value; debounce persistence, not this callback. */
+  onChange: (value: CommentValue) => void;
+  /** A keyboard intent only. The host owns requests, buttons, loading and errors. */
+  onSubmitRequest?: () => void;
+  disabled?: boolean;
+  enableDocuments?: boolean;
+  placeholder?: string;
+  submitMode?: 'enter' | 'mod-enter';
+  className?: string;
+  /** Mount the suggestion panel inside a Dialog/Sheet when appropriate. */
+  portalContainer?: HTMLElement;
+}
+
+export interface CommentInputHandle {
+  /** Read the latest wire content. Does not validate whether the host should send. */
+  getContent(): CommentApiContent[];
+  /** Clear the body as an undoable edit; keep the same editing session. */
+  clear(): void;
+  setEditable(editable: boolean): void;
+  focus(): void;
+}
+
+/** Internal bridge; the public entry stays available before Tiptap has loaded. */
+export interface CommentEditorProps extends Omit<CommentInputProps, 'ref'> {
+  editorRef: Ref<CommentInputHandle>;
+}
+
+/** The host decides how to display a profile or navigate a reference. */
+export type CommentMentionClickHandler = (
+  ref: MentionRef,
+  anchor: HTMLElement,
+) => void;