@lark-apaas/coding-template-nestjs-react-fullstack 0.1.56 → 0.1.57-alpha.20261103143319

package/template/client/src/components/business-ui/record-comments/comment-panel.tsx

@@ -0,0 +1,231 @@
+import type { CommentComposerProps, CommentListProps, CommentPanelProps, CommentsProviderProps, CommentTarget } from './comment-panel.contract';
+import { CommentMutations } from './internal/mutations';
+import { buildPanelThreads, CommentPageLoader, preparePanelDeletion, preparePanelEdit, loadPanelReactionDetails, preparePanelComment } from './internal/model';
+import { DiscussionComposerView, DiscussionLayout, DiscussionList, DiscussionProvider } from './internal/discussion';
+import { commentExtensionFeatures, withDocumentSource } from './extensions';
+import { COMMENT_THEME_CLASS } from './internal/model';
+import { LoaderCircle } from 'lucide-react';
+import { forwardRef, useCallback, useEffect, useMemo, useReducer, useRef, useState, useSyncExternalStore } from 'react';
+import './internal/styles.css';
+
+function ReadStatus({ loading, error, onRetry, empty, hasMore }: Pick<CommentPanelProps, 'loading' | 'error' | 'onRetry'> & { empty: boolean; hasMore?: boolean }) {
+  const [failure, setFailure] = useState('');
+  const [retrying, setRetrying] = useState(false);
+  const busy = useRef(false);
+  // A successful external read must clear a previous retry failure as well.
+  useEffect(() => setFailure(''), [error]);
+  const pending = loading || retrying;
+  const message = failure || error;
+  if (!empty && !pending && !message) return null;
+  const state = pending ? 'loading' : message ? 'error' : 'empty';
+  return <div className={`replica-panel-status${empty ? ' replica-panel-placeholder' : ''}`}
+    data-state={state} role={state === 'error' ? 'alert' : 'status'} aria-busy={pending}>
+    <div className="replica-panel-status-content">
+      <span>{pending ? <LoaderCircle className="size-4 animate-spin text-primary" aria-label="正在加载评论" />
+        : message || (empty && !hasMore ? '当前记录暂无评论' : null)}</span>
+      {!pending && message && onRetry && <button type="button" onClick={async () => {
+        if (busy.current) return;
+        busy.current = true; setRetrying(true); setFailure('');
+        try { await onRetry(); }
+        catch (cause) { setFailure(cause instanceof Error ? cause.message : '刷新失败，请重试'); }
+        finally { busy.current = false; setRetrying(false); }
+      }}>重试刷新</button>}
+    </div>
+  </div>;
+}
+
+function nearestScrollContainer(node: HTMLElement): HTMLElement | null {
+  for (let parent = node.parentElement; parent; parent = parent.parentElement) {
+    if (/(auto|scroll)/.test(getComputedStyle(parent).overflowY) && parent.clientHeight > 0) return parent;
+  }
+  return null;
+}
+
+function PaginationFooter({ pagination, loading, getScrollContainer }: Pick<CommentPanelProps, 'pagination' | 'loading' | 'getScrollContainer'>) {
+  const sentinel = useRef<HTMLDivElement>(null);
+  const root = useRef<HTMLElement | null>(null);
+  const [gate] = useState(() => new CommentPageLoader());
+  const [, refresh] = useReducer((value: number) => value + 1, 0);
+  const latest = useRef({ pagination, loading });
+  latest.current = { pagination, loading };
+  const alive = useRef(true);
+  const run = useRef((manual = false) => { void manual; });
+  run.current = (manual = false) => {
+    const current = latest.current;
+    if (!alive.current || current.loading || !current.pagination?.hasMore || current.pagination.loading || gate.pending) return;
+    if (!manual && (gate.error || current.pagination.error || gate.automaticLoads >= 3)) return;
+    const promise = gate.load(current.pagination, manual);
+    refresh();
+    void promise.finally(() => { if (alive.current) refresh(); });
+  };
+  const check = useCallback(() => {
+    const element = sentinel.current;
+    if (!element) return;
+    const bounds = element.getBoundingClientRect();
+    const viewport = root.current?.getBoundingClientRect();
+    const visibleTop = Math.max(0, viewport?.top ?? 0);
+    const visibleBottom = Math.min(window.innerHeight, viewport?.bottom ?? window.innerHeight);
+    if (visibleBottom > visibleTop && bounds.top <= visibleBottom + 200 && bounds.bottom >= visibleTop)
+      run.current();
+  }, []);
+  useEffect(() => {
+    alive.current = true;
+    const element = sentinel.current;
+    if (!element) return;
+    root.current = getScrollContainer ? getScrollContainer() : nearestScrollContainer(element);
+    const container = root.current ?? window;
+    const observer = new IntersectionObserver(() => check(), { root: root.current, rootMargin: '0px 0px 200px 0px' });
+    observer.observe(element);
+    const resize = new ResizeObserver(check);
+    resize.observe(root.current ?? document.documentElement);
+    const resume = (event: Event) => {
+      if (event instanceof WheelEvent && event.deltaY > 0) gate.automaticLoads = 0;
+      if (event instanceof KeyboardEvent && ['PageDown', 'End', 'ArrowDown'].includes(event.key)) gate.automaticLoads = 0;
+      check();
+    };
+    container.addEventListener('scroll', check, { passive: true });
+    if (root.current) window.addEventListener('scroll', check, { passive: true });
+    container.addEventListener('wheel', resume, { passive: true });
+    container.addEventListener('keydown', resume);
+    return () => {
+      alive.current = false;
+      observer.disconnect(); resize.disconnect();
+      container.removeEventListener('scroll', check);
+      window.removeEventListener('scroll', check);
+      container.removeEventListener('wheel', resume);
+      container.removeEventListener('keydown', resume);
+    };
+  }, [check, gate, getScrollContainer]);
+  useEffect(() => {
+    const frame = requestAnimationFrame(check);
+    return () => cancelAnimationFrame(frame);
+  });
+  const error = pagination?.hasMore && (gate.error || pagination.error);
+  const pending = gate.pending || pagination?.loading;
+  return <div ref={sentinel} className={pagination?.hasMore ? 'replica-panel-pagination' : undefined} aria-live="polite">
+    {pagination?.hasMore && (error ? <><span role="alert">{error}</span><button type="button" disabled={pending} onClick={() => run.current(true)}>重试加载</button></>
+      : pending ? <LoaderCircle className="size-4 animate-spin text-primary" aria-label="正在加载更多评论" />
+        : pagination?.hasMore ? <button type="button" disabled={loading} onClick={() => run.current(true)}>继续加载</button>
+          : null)}
+  </div>;
+}
+
+function PanelSession(props: CommentsProviderProps) {
+  const latest = useRef(props);
+  latest.current = props;
+  const locks = useRef(new Set<string>());
+  const [submitted, setSubmitted] = useState<string>();
+  const [mutations] = useState(() => new CommentMutations());
+  useSyncExternalStore(mutations.subscribe, mutations.getVersion, mutations.getVersion);
+  const base = buildPanelThreads(props);
+  const comments = mutations.view(base);
+  useEffect(() => {
+    mutations.activate();
+    return () => mutations.dispose();
+  }, [mutations]);
+  useEffect(() => { mutations.reconcile(base); }, [base, mutations]);
+  async function locked<T>(key: string, action: () => Promise<T>): Promise<T> {
+    if (locks.current.has(key)) throw new Error('该评论正在处理中，请稍后重试');
+    locks.current.add(key);
+    try { return await action(); }
+    finally { locks.current.delete(key); }
+  }
+  const allowCompose = Boolean(props.onAddComment || props.images?.onAddComment);
+  const currentUser = props.currentUserID == null ? undefined
+    : { kind: 'user' as const, idType: 'apaas-user' as const, id: String(props.currentUserID) };
+  return <DiscussionProvider panel={{
+    source: props.mentionSource,
+    currentUser,
+    comments,
+    allowCompose,
+    optimisticMutations: true,
+    onRetryMutation: (id) => mutations.retry(id),
+    showReactions: Boolean(props.reactions),
+    allowReact: Boolean(props.reactions?.onChange),
+    enableImages: Boolean(props.images?.onAddComment),
+    enableEditImages: Boolean(props.images?.onUpdateComment),
+    enablePrivateComments: false,
+    enableDocuments: props.enableDocuments ?? false,
+    autoScrollNewReplies: false,
+    emptyState: null,
+    submittedReplyID: submitted ? mutations.replyID(submitted) : undefined,
+    onScrolledToReply: () => setSubmitted(undefined),
+    listHeader: <ReadStatus loading={props.loading} error={props.error} onRetry={props.onRetry}
+      empty={!comments.some((thread) => thread.replies.length > 0)} hasMore={props.pagination?.hasMore} />,
+    listFooter: props.pagination && <PaginationFooter pagination={props.pagination}
+      loading={props.loading || Boolean(props.error)} getScrollContainer={props.getScrollContainer} />,
+    onMentionClick: props.onMentionClick,
+    getCommentLink: (commentID, reply) => props.getCommentLink?.({ recordID: props.recordID, commentID, replyID: reply.replyID }) ?? '',
+    onSubmit: (draft) => {
+      const current = latest.current;
+      preparePanelComment(current, draft); // Validate before accepting/clearing the draft.
+      const thread = base.find((item) => item.commentID === draft.commentID);
+      const id = mutations.add(thread, draft, currentUser, () => preparePanelComment(latest.current, draft)());
+      setSubmitted(id);
+    },
+    onEdit: (commentID, replyID, value, images) => {
+      const draft = { value, images, private: false };
+      preparePanelEdit(latest.current, commentID, replyID, draft);
+      const thread = base.find((item) => item.commentID === commentID)!;
+      mutations.edit(thread, replyID, draft, () => preparePanelEdit(latest.current, commentID, replyID, draft)());
+    },
+    onDelete: (commentID, replyID) => {
+      if (!replyID) throw new Error('未选择要删除的评论');
+      preparePanelDeletion(latest.current, commentID, replyID);
+      const thread = base.find((item) => item.commentID === commentID)!;
+      mutations.delete(thread, replyID, () => preparePanelDeletion(latest.current, commentID, replyID)());
+    },
+    onToggleReaction: async (commentID, replyID, emojiKey) => {
+      await locked(replyID, async () => {
+        const current = latest.current;
+        const feature = current.reactions;
+        if (!feature?.onChange) throw new Error('未提供回应写入能力');
+        const target: CommentTarget = { recordID: current.recordID, commentID, replyID };
+        if (feature.canChange?.(target) === false) throw new Error('表情状态尚未加载或当前身份不可用');
+        const existing = feature.getReactions(target).find((reaction) => reaction.emojiKey === emojiKey ||
+          (emojiKey === 'THUMBSUP' && reaction.emojiKey === 'MediumThumbsup'));
+        await feature.onChange({ ...target, emojiKey: existing?.emojiKey ?? emojiKey, action: existing?.reactedByMe ? 'remove' : 'add' });
+      });
+    },
+    loadReactionDetails: props.reactions?.loadUsers ? (commentID, replyID, signal) => loadPanelReactionDetails(
+      latest.current, { recordID: props.recordID, commentID, replyID }, signal,
+    ) : undefined,
+  }}>{props.children}</DiscussionProvider>;
+}
+
+/** Shared record session, with no layout DOM and no persistence implementation. */
+export function CommentsProvider(props: CommentsProviderProps) {
+  const features = useMemo(() => commentExtensionFeatures(props.extensions), [props.extensions]);
+  const mentionSource = useMemo(() => features.documents
+    ? withDocumentSource(props.mentionSource, features.documents) : props.mentionSource,
+  [props.mentionSource, features.documents]);
+  return <PanelSession key={JSON.stringify([props.scopeKey, props.recordID])} {...props}
+    mentionSource={mentionSource} reactions={features.reactions ?? props.reactions}
+    images={features.images ?? props.images} enableDocuments={Boolean(features.documents) || props.enableDocuments} />;
+}
+
+/** The theme is scoped to this leaf; no panel heading, card or fixed height. */
+export const CommentList = forwardRef<HTMLDivElement, CommentListProps>(function CommentList(
+  { className = '', style, ...props }, ref,
+) {
+  return <div {...props} ref={ref} data-slot="comment-list"
+    className={`${COMMENT_THEME_CLASS} replica-comment-panel replica-discussion ${className}`} style={{ height: 'auto', ...style }}>
+    <DiscussionList style={{ overflowY: 'visible' }} />
+  </div>;
+});
+
+export const CommentComposer = forwardRef<HTMLDivElement, CommentComposerProps>(function CommentComposer(
+  { placeholder, disabled, className = '', style, ...props }, ref,
+) {
+  return <div {...props} ref={ref} data-slot="comment-composer"
+    className={`${COMMENT_THEME_CLASS} replica-discussion ${className}`} style={{ height: 'auto', ...style }}>
+    <DiscussionComposerView placeholder={placeholder} disabled={disabled} />
+  </div>;
+});
+
+/** Compatibility composition with the existing heading, list and footer layout. */
+export function CommentPanel({ className, style, ...props }: CommentPanelProps) {
+  return <CommentsProvider {...props}>
+    <div className={`replica-comment-panel ${className ?? ''}`} style={style}><DiscussionLayout /></div>
+  </CommentsProvider>;
+}

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

@@ -0,0 +1,129 @@
+import type { CommentImageFeature, CommentReactionFeature } from './comment-panel.contract';
+import type { CommentDataSource, CommentDocumentSource, MentionResult } from './types';
+import { mentionKey } from './internal/model';
+
+/** Per-provider capabilities. No global registration, credentials or requests. */
+export type CommentExtension =
+  | { readonly type: 'reactions'; readonly options: CommentReactionFeature }
+  | { readonly type: 'documents'; readonly source: CommentDocumentSource }
+  | { readonly type: 'images'; readonly options: CommentImageFeature };
+
+export function commentReactions(options: CommentReactionFeature): CommentExtension {
+  return { type: 'reactions', options };
+}
+
+export function commentDocuments(source: CommentDocumentSource): CommentExtension {
+  return { type: 'documents', source };
+}
+
+/** Requires the host's upload/persistence/readback implementation; no Bitable image API is supplied. */
+export function commentImages(options: CommentImageFeature): CommentExtension {
+  return { type: 'images', options };
+}
+
+/** Normalize registrations once per array. Never combine two implementations of the same capability. */
+export function commentExtensionFeatures(extensions: readonly CommentExtension[] = []) {
+  const result: { reactions?: CommentReactionFeature; images?: CommentImageFeature; documents?: CommentDocumentSource } = {};
+  const seen = new Set<string>();
+  for (const extension of extensions) {
+    if (seen.has(extension.type)) throw new Error(`Duplicate comment extension: ${extension.type}`);
+    seen.add(extension.type);
+    switch (extension.type) {
+      case 'reactions': result.reactions = extension.options; break;
+      case 'images': result.images = extension.options; break;
+      case 'documents': result.documents = extension.source; break;
+      default: throw new Error('Unsupported comment extension');
+    }
+  }
+  return result;
+}
+
+/** Keep Miaoda people IDs and cloud-document tokens in their own services. */
+export function withDocumentSource(
+  people: CommentDataSource,
+  documents: CommentDocumentSource,
+): CommentDataSource {
+  const load = async (
+    args: Parameters<CommentDataSource['search']>[0],
+    recommend: boolean,
+  ) => {
+    const fetchSource = (
+      source: CommentDataSource | CommentDocumentSource,
+      kind: 'user' | 'document',
+      cursor?: string,
+    ) =>
+      recommend && source.recommend
+        ? source.recommend({ ...args, kind, cursor })
+        : source.search({ ...args, kind, cursor });
+    if (args.kind === 'user') return fetchSource(people, 'user', args.cursor);
+    if (args.kind === 'document')
+      return fetchSource(documents, 'document', args.cursor);
+    const cursor: { user?: string; document?: string } = args.cursor
+      ? JSON.parse(args.cursor)
+      : {};
+    if (
+      !cursor ||
+      typeof cursor !== 'object' ||
+      [cursor.user, cursor.document].some(
+        (value) => value !== undefined && typeof value !== 'string',
+      )
+    )
+      throw new Error('分页参数无效');
+    const exhausted: Awaited<ReturnType<CommentDataSource['search']>> = {
+      items: [],
+    };
+    const requestUsers = !args.cursor || cursor.user !== undefined;
+    const requestDocs = !args.cursor || cursor.document !== undefined;
+    const pages = await Promise.allSettled([
+      requestUsers
+        ? fetchSource(people, 'user', cursor.user)
+        : exhausted,
+      requestDocs
+        ? fetchSource(documents, 'document', cursor.document)
+        : exhausted,
+    ]);
+    if ((!requestUsers || pages[0].status === 'rejected') && (!requestDocs || pages[1].status === 'rejected'))
+      throw new Error('人员和文档搜索失败，请重试');
+    // A disabled/unavailable document capability must not break existing @people.
+    const users = pages[0].status === 'fulfilled' ? pages[0].value : exhausted;
+    const docs = pages[1].status === 'fulfilled' ? pages[1].value : exhausted;
+    return {
+      items: [
+        ...users.items.filter((item) => item.ref.kind === 'user'),
+        ...docs.items.filter((item) => item.ref.kind === 'document'),
+      ],
+      nextCursor:
+        users.nextCursor || docs.nextCursor
+          ? JSON.stringify({
+              user: users.nextCursor,
+              document: docs.nextCursor,
+            })
+          : undefined,
+    };
+  };
+  return {
+    ...people,
+    scopeKey: JSON.stringify([people.scopeKey, documents.scopeKey]),
+    search: (args) => load(args, false),
+    recommend: (args) => load({ ...args, query: '' }, true),
+    async resolve(refs, signal) {
+      const users = refs.filter((ref) => ref.kind === 'user');
+      const docs = refs.filter((ref) => ref.kind === 'document');
+      // One failed service must not hide successful metadata from the other.
+      const results = await Promise.allSettled([
+        users.length ? people.resolve(users, signal) : [],
+        docs.length ? documents.resolve(docs, signal) : [],
+      ]);
+      signal.throwIfAborted();
+      const byKey = new Map<string, MentionResult>();
+      for (const result of results)
+        if (result.status === 'fulfilled')
+          for (const item of result.value)
+            byKey.set(mentionKey(item.ref), item);
+      return refs.map(
+        (ref) =>
+          byKey.get(mentionKey(ref)) || { ref, status: 'error' as const },
+      );
+    },
+  };
+}

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

@@ -0,0 +1,9 @@
+export { CommentPanel, CommentsProvider, CommentList, CommentComposer } from './comment-panel';
+export { createAppCommentSource } from './app-source';
+export { commentReactions, commentDocuments, commentImages, withDocumentSource } from './extensions';
+export type { CommentExtension } from './extensions';
+export type * from './comment-panel.contract';
+export type { CommentDataSource, CommentDocumentSource, CommentMentionClickHandler, MentionRef, MentionOption, MentionResult, MentionKind, DocumentMentionMetadata } from './types';
+
+// URL helpers for external document adapters; no requests or permissions inside.
+export { documentRefFromUrl, safeUrl } from './internal/model';