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

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

@@ -0,0 +1,149 @@
+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;
+}
+
+/** 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/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} />