@lark-apaas/coding-template-nestjs-react-fullstack 0.1.54 → 0.1.55-alpha.20261030035108

package/template/client/src/components/business-ui/comment/mention-suggestions.tsx

@@ -0,0 +1,312 @@
+import * as React from 'react';
+import { useLayoutEffect } from 'react';
+import { createPortal } from 'react-dom';
+import { autoUpdate } from '@floating-ui/dom';
+import { LoaderCircle } from 'lucide-react';
+import { DocumentIcon } from './document-icon';
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar';
+import { Button } from '@/components/ui/button';
+import { ScrollArea } from '@/components/ui/scroll-area';
+import { cn } from '@/lib/utils';
+import { COMMENT_THEME_CLASS } from './mention-appearance';
+import { mentionKey, safeUrl } from './content';
+import type { MentionOption } from './types';
+
+function HighlightedLabel({ label, query }: { label: string; query: string }) {
+  const index = query ? label.toLowerCase().indexOf(query.toLowerCase()) : -1;
+  if (index < 0) return <>{label}</>;
+  return (
+    <>
+      {label.slice(0, index)}
+      <span className="text-primary">
+        {label.slice(index, index + query.length)}
+      </span>
+      {label.slice(index + query.length)}
+    </>
+  );
+}
+
+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;
+  error?: string;
+  retry: () => void;
+  loadMore: () => void;
+  hasMore: boolean;
+};
+
+/** Source: miaoda UdMentionPlugin + UD MentionPanel/OptionItem/index.less.
+ * hiddenTab=true, footer=false, 360px width, 48px rows, 2px row gap,
+ * 8px vertical list padding, 8px row margin, 8px avatar gap.
+ */
+export function MentionSuggestions({
+  container,
+  anchor,
+  editorElement,
+  id,
+  items,
+  selected,
+  query = '',
+  onSelect,
+  onHover,
+  loading,
+  error,
+  retry,
+  loadMore,
+  hasMore,
+}: Props) {
+  const panel = React.useRef<HTMLDivElement>(null);
+  const initialLoading = loading && !items.length;
+  const list = React.useRef<HTMLDivElement>(null);
+  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 width = viewport.clientWidth || window.innerWidth;
+      const height = viewport.clientHeight || window.innerHeight;
+      const below = height - rect.bottom;
+      const above = rect.top;
+      // Match getMentionPositionInfo's preferred 417px box, including when the list is short.
+      const up = below < 431 && (above >= 431 || above > below);
+      const maxHeight = Math.max(64, Math.min(417, (up ? above : below) - 14));
+      const boxWidth = Math.min(360, Math.max(0, width - 24));
+      element.style.width = `${boxWidth}px`;
+      const computed = window.getComputedStyle(element);
+      const borderHeight =
+        (parseFloat(computed.borderTopWidth) || 0) +
+        (parseFloat(computed.borderBottomWidth) || 0);
+      // The actual list includes padding, row margins and wrapped status text.
+      // Its measured size must fit inside the panel's borders, not underneath them.
+      const contentHeight = list.current?.getBoundingClientRect().height || 0;
+      const naturalHeight = Math.max(
+        64,
+        Math.ceil(contentHeight + borderHeight),
+      );
+      const boxHeight = Math.min(naturalHeight, maxHeight);
+      const preferLeft = width - rect.left < 372 && rect.right >= 372;
+      const left = Math.max(
+        12,
+        Math.min(
+          preferLeft ? rect.right - boxWidth : rect.left,
+          width - boxWidth - 12,
+        ),
+      );
+      Object.assign(element.style, {
+        left: `${left}px`,
+        top: `${up ? Math.max(12, rect.top - boxHeight - 2) : rect.bottom + 2}px`,
+        width: `${boxWidth}px`,
+        height: `${boxHeight}px`,
+        visibility: 'visible',
+      });
+    };
+    const stopPositioning = autoUpdate(reference, element, update);
+    const observer =
+      typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(update);
+    if (list.current) observer?.observe(list.current);
+    return () => {
+      stopPositioning();
+      observer?.disconnect();
+    };
+  }, [
+    anchor,
+    editorElement,
+    container,
+    items,
+    initialLoading,
+    error,
+    hasMore,
+    query,
+  ]);
+  useLayoutEffect(() => {
+    panel.current
+      ?.querySelector('[aria-selected="true"]')
+      ?.scrollIntoView({ block: 'nearest' });
+  }, [selected, items]);
+  return createPortal(
+    <div
+      ref={panel}
+      data-comment-suggestions
+      className={cn(
+        COMMENT_THEME_CLASS,
+        'fixed z-50 overflow-hidden rounded-[6px] border border-border bg-popover text-popover-foreground shadow-[0_6px_24px_rgba(31,35,41,0.08),0_10px_15px_-3px_rgba(0,0,0,0.1),0_4px_6px_-4px_rgba(0,0,0,0.1)]',
+      )}
+      style={{
+        visibility: 'hidden',
+        width: 360,
+        minHeight: 64,
+        maxHeight: 417,
+      }}
+      onPointerDown={(event) => event.preventDefault()}
+      onWheel={(event) => event.stopPropagation()}
+    >
+      <span role="status" className="sr-only">
+        {loading ? '正在搜索' : `${items.length} 个结果`}
+      </span>
+      <ScrollArea className="h-full w-full">
+        <div
+          ref={list}
+          id={id}
+          role="listbox"
+          aria-label="提及搜索结果"
+          aria-busy={loading}
+          className="py-2"
+        >
+          {items.map((item, index) => {
+            const active = selected === index;
+            return (
+              <div
+                key={mentionKey(item.ref)}
+                id={`${id}-${index}`}
+                role="option"
+                aria-selected={active}
+                onPointerMove={() => {
+                  if (!active) onHover(index);
+                }}
+                onClick={() => {
+                  onSelect(item);
+                }}
+                className={cn(
+                  'mx-2 mb-0.5 flex h-12 cursor-pointer items-center gap-2 rounded-[4px] px-2 py-1',
+                  active && 'bg-[var(--comment-hover)]',
+                  !active && 'hover:bg-[var(--comment-hover)]',
+                )}
+              >
+                {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 className="min-w-0 flex-1">
+                  <div
+                    className="truncate text-sm font-normal leading-[22px] text-foreground"
+                    title={item.label}
+                  >
+                    <HighlightedLabel label={item.label} query={query} />
+                    {item.ref.kind === 'document' && item.isExternal ? (
+                      <span className="ml-1 rounded-[2px] border border-border px-1 text-xs text-subtle-foreground">
+                        外部
+                      </span>
+                    ) : null}
+                  </div>
+                  {item.description ? (
+                    <div
+                      className="truncate text-xs leading-5 text-muted-foreground"
+                      title={item.description}
+                    >
+                      {item.description}
+                    </div>
+                  ) : null}
+                </div>
+              </div>
+            );
+          })}
+          {initialLoading ? (
+            <div role="status" aria-label="正在搜索" className="px-4">
+              {[0, 1, 2, 3].map((key) => (
+                <div
+                  key={key}
+                  aria-hidden
+                  className="flex h-12 animate-pulse items-center gap-2 py-1"
+                >
+                  <span className="size-8 shrink-0 rounded-full bg-muted" />
+                  <span className="space-y-1.5">
+                    <span className="block h-3.5 w-[70px] rounded-md bg-muted" />
+                    <span className="block h-3.5 w-[200px] max-w-full rounded-md bg-muted" />
+                  </span>
+                </div>
+              ))}
+            </div>
+          ) : null}
+          {!items.length && !loading && !error ? (
+            <div
+              role="status"
+              className="px-4 py-4 text-sm leading-[22px] text-foreground"
+            >
+              {query ? '没有匹配结果，换个关键词试试吧' : '列表为空'}
+            </div>
+          ) : null}
+          {error ? (
+            <div role="alert" className="px-4 py-4 text-sm leading-[22px]">
+              <button
+                type="button"
+                className="inline text-left"
+                disabled={loading}
+                onClick={retry}
+                title="点击重新加载"
+              >
+                <span
+                  aria-hidden
+                  className="mr-2 inline-block not-italic [line-height:0]"
+                  style={{ color: 'var(--comment-warning)' }}
+                >
+                  <svg
+                    aria-hidden
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    style={{
+                      width: '1em',
+                      height: '1em',
+                      display: 'inline-block',
+                      verticalAlign: '-0.14em',
+                    }}
+                  >
+                    <path
+                      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"
+                      fill="currentColor"
+                    />
+                  </svg>
+                </span>
+                加载失败，请检查网络后重试
+              </button>
+            </div>
+          ) : null}
+          {hasMore ? (
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              className="mx-3 my-2 text-primary"
+              disabled={loading}
+              onClick={loadMore}
+            >
+              加载更多
+            </Button>
+          ) : null}
+        </div>
+      </ScrollArea>
+      {loading && items.length ? (
+        <div className="absolute inset-0 flex items-center justify-center bg-popover/60">
+          <LoaderCircle
+            aria-label="正在搜索"
+            className="size-5 animate-spin text-primary"
+          />
+        </div>
+      ) : null}
+    </div>,
+    container || document.body,
+  );
+}

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

@@ -0,0 +1,154 @@
+import type { Ref } from 'react';
+
+export type MentionRef =
+  | { kind: 'user'; id: string; idType: 'apaas-user' }
+  | { 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 }
+  | { type: 'link'; url: string };
+
+export interface CommentSubmitPayload {
+  content: CommentApiContent[];
+}
+
+/** Storage result, not an assumed Base comment image protocol. */
+export interface CommentImageResult {
+  id: string;
+  url: string;
+  filePath?: string;
+  bucketId?: string;
+}
+
+export interface CommentImage {
+  id: string;
+  name: string;
+  size: number;
+  previewUrl: string;
+  status: 'uploading' | 'uploaded' | 'error';
+  result?: CommentImageResult;
+  error?: string;
+}
+
+export type CommentImageUploader = (
+  file: File,
+  options: { signal: AbortSignal },
+) => Promise<CommentImageResult>;
+
+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;
+  /** Images are attachments below the body, never inline editor nodes. */
+  enableImages?: boolean;
+  uploadImage?: CommentImageUploader;
+  maxImages?: number;
+  /** Bytes; defaults to 10 MiB. */
+  maxImageSize?: number;
+  onImagesChange?: (images: CommentImage[]) => void;
+  /** Optional controlled permission intent. The host performs actual grants. */
+  grantMentionAccess?: boolean;
+  onGrantMentionAccessChange?: (checked: boolean) => void;
+  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[];
+  getImages(): CommentImage[];
+  /** Clear the body as an undoable edit; keep the same editing session. */
+  clear(): void;
+  /** Attachments have their own lifecycle, independent of body undo history. */
+  clearImages(): void;
+  setEditable(editable: boolean): void;
+  focus(): void;
+}
+
+/** Internal bridge; the public entry stays available before the editing module 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;

package/template/client/src/components/business-ui/comment/use-mention-search.ts

@@ -0,0 +1,107 @@
+import { useEffect, useRef, useState } from 'react';
+import { mentionKey } from './content';
+import type {
+  CommentDataSource,
+  MentionKind,
+  MentionOption,
+} from './types';
+
+interface Result {
+  key: string;
+  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 [state, setState] = useState<Result>({
+    key: '',
+    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,
+        items: cursor && previous.key === key ? 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,
+            items: [...unique.values()],
+            nextCursor: result.nextCursor,
+            loading: false,
+          };
+        });
+      } catch (error) {
+        if (!abort.signal.aborted && currentKey.current === key)
+          setState((previous) => ({
+            ...previous,
+            key,
+            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]);
+  const result =
+    state.key === key ? state : { key, items: [], loading: Boolean(session) };
+  return {
+    ...result,
+    loadMore: () => runRef.current(result.nextCursor),
+    retry: () => runRef.current(),
+  };
+}

package/template/client/src/components/business-ui/user-display/user-display.tsx

@@ -13,18 +13,6 @@ import {
   PopoverTrigger,
 } from '@client/src/components/ui/popover';
 
-/**
- * 阻止 Popover 打开时的自动聚焦。
- *
- * Radix 的 FocusScope 在弹层挂载时会把焦点给容器里第一个可聚焦元素。人员卡片
- * 挂载那一刻内容就已经在了（飞书名片里有「消息」等按钮），于是一打开就有个
- * 按钮带上焦点环。这是张只读预览卡，焦点应该留在触发器上 —— Radix 自己的
- * HoverCard 也是这么处理的。
- */
-const handleProfileOpenAutoFocus = (event: Event) => {
-  event.preventDefault();
-};
-
 export interface IUserDisplayProps {
   /**
    * 用户列表
@@ -100,7 +88,6 @@ export const UserDisplay: React.FC<IUserDisplayProps> = ({
           <PopoverContent
             align="start"
             sideOffset={8}
-            onOpenAutoFocus={handleProfileOpenAutoFocus}
             className="w-[320px] border-0 border-border/50 bg-card p-0 shadow-[0px_8px_24px_8px_rgba(31,35,41,0.04),0px_6px_12px_rgba(31,35,41,0.04),0px_4px_8px_-8px_rgba(31,35,41,0.06)]"
           >
             <UserProfile value={user} />