@lark-base-open/base-database-cli 1.0.0

package/templates/database-starter/page/src/components/UserSelectorPanel/index.tsx

@@ -0,0 +1,478 @@
+import React, {
+  useCallback,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type KeyboardEventHandler,
+} from 'react'
+
+import { cn } from '../../lib/cn'
+import './index.css'
+import { requestUsers, type SearchUsersData, type User } from './user-search'
+
+export type {
+  SearchUsers,
+  SearchUsersData,
+  SearchUsersResponse,
+  User,
+  UserAvatar,
+} from './user-search'
+
+const SEARCH_DEBOUNCE_MS = 400
+const SEARCH_CACHE_TTL_MS = 30_000
+const RECORD_CREATOR_AVATAR_URL =
+  'https://lf-package-cn.feishucdn.com/obj/feishu-static/ccm/static_resource/scm_upload/base_filter_current_user.png'
+
+interface SearchUsersCacheEntry {
+  expiresAt: number
+  request: Promise<SearchUsersData>
+}
+
+const searchUsersCache = new Map<string, SearchUsersCacheEntry>()
+
+export type UserSelectorAction = 'Select' | 'Remove' | 'Clear'
+export type UserSelectorMode = 'multiple'
+export type UserSelectorSearchAction = 'Input' | 'AutoClear'
+export type UserSelectorValue = User | User[]
+
+export interface UserSelectorPanelProps {
+  value?: UserSelectorValue | null
+  defaultValue?: UserSelectorValue
+  onChange?: (
+    value: UserSelectorValue | undefined,
+    meta: { option: User | undefined; action: UserSelectorAction },
+  ) => void
+  onSelect?: (user: User, meta: { option: User }) => void
+  onClose?: () => void
+  onSelectRecordCreator?: () => void
+  getUserDescription?: (user: User) => string | undefined
+  onSearch?: (value: string, meta: { action: UserSelectorSearchAction }) => void
+  loading?: boolean
+  mode?: UserSelectorMode
+  onKeyDown?: KeyboardEventHandler<HTMLInputElement>
+}
+
+/**
+ * 管理成员搜索与选择状态，可独立渲染或由 UserSelectorEditor 组合。
+ */
+export default function UserSelectorPanel(
+  props: UserSelectorPanelProps,
+): React.JSX.Element {
+  const {
+    value: controlledValue,
+    defaultValue,
+    onChange,
+    onSelect,
+    onClose,
+    onSelectRecordCreator,
+    getUserDescription,
+    onSearch,
+    loading: externalLoading = false,
+    mode,
+    onKeyDown,
+  } = props
+  const isValueControlled = Object.prototype.hasOwnProperty.call(props, 'value')
+  const [innerValue, setInnerValue] = useState(defaultValue)
+  const [query, setQuery] = useState('')
+  const [users, setUsers] = useState<User[]>([])
+  const [requestLoading, setRequestLoading] = useState(false)
+  const [error, setError] = useState('')
+  const [isComposing, setIsComposing] = useState(false)
+  const [activeIndex, setActiveIndex] = useState(-1)
+  const inputRef = useRef<HTMLInputElement>(null)
+  const requestSequenceRef = useRef(0)
+  const generatedListboxId = useId()
+  const value = isValueControlled ? (controlledValue ?? undefined) : innerValue
+  const selectedUsers = Array.isArray(value) ? value : value ? [value] : []
+  const selectedUsersRef = useRef(selectedUsers)
+  selectedUsersRef.current = selectedUsers
+  const isMultiple = mode === 'multiple'
+  const loading = externalLoading || requestLoading
+  const optionCount = users.length + (onSelectRecordCreator ? 1 : 0)
+  const activeOptionId =
+    activeIndex >= 0 ? `${generatedListboxId}-option-${activeIndex}` : undefined
+  const isEmpty = !loading && optionCount === 0
+
+  const getSearchResult = useCallback((keyword: string) => {
+    const cacheKey = keyword.trim()
+    const cachedResult = searchUsersCache.get(cacheKey)
+    if (cachedResult && cachedResult.expiresAt > Date.now()) {
+      return cachedResult.request
+    }
+    searchUsersCache.delete(cacheKey)
+
+    const request = requestUsers(cacheKey)
+      .then(normalizeSearchUsersResponse)
+      .catch((error: unknown) => {
+        if (searchUsersCache.get(cacheKey)?.request === request) {
+          searchUsersCache.delete(cacheKey)
+        }
+        throw error
+      })
+    searchUsersCache.set(cacheKey, {
+      expiresAt: Date.now() + SEARCH_CACHE_TTL_MS,
+      request,
+    })
+    return request
+  }, [])
+
+  const updateQuery = useCallback(
+    (nextQuery: string, action: UserSelectorSearchAction) => {
+      setQuery(nextQuery)
+      onSearch?.(nextQuery, { action })
+    },
+    [onSearch],
+  )
+
+  const runSearch = useCallback(
+    async (keyword: string) => {
+      const requestSequence = ++requestSequenceRef.current
+      setRequestLoading(true)
+      setError('')
+      setUsers([])
+
+      try {
+        const data = await getSearchResult(keyword)
+        if (requestSequence !== requestSequenceRef.current) return
+
+        const missingSelectedUsers = selectedUsersRef.current.filter(
+          (selectedUser) =>
+            !data.users.some((user) => user.user_id === selectedUser.user_id),
+        )
+        const responseUsers =
+          missingSelectedUsers.length > 0
+            ? [...data.users, ...missingSelectedUsers]
+            : data.users
+
+        setUsers(responseUsers)
+      } catch (searchError) {
+        if (requestSequence !== requestSequenceRef.current) return
+        setError(
+          searchError instanceof Error ? searchError.message : '搜索成员失败',
+        )
+        setUsers([])
+      } finally {
+        if (requestSequence === requestSequenceRef.current) {
+          setRequestLoading(false)
+        }
+      }
+    },
+    [getSearchResult],
+  )
+
+  useEffect(() => {
+    inputRef.current?.focus()
+  }, [])
+
+  useEffect(() => {
+    requestSequenceRef.current += 1
+    setActiveIndex(-1)
+    if (isComposing) {
+      setRequestLoading(false)
+      return
+    }
+
+    setRequestLoading(true)
+    const timer = window.setTimeout(
+      () => {
+        void runSearch(query)
+      },
+      query.trim() ? SEARCH_DEBOUNCE_MS : 0,
+    )
+
+    return () => {
+      window.clearTimeout(timer)
+      requestSequenceRef.current += 1
+    }
+  }, [isComposing, query, runSearch])
+
+  const closePanel = () => {
+    requestSequenceRef.current += 1
+    updateQuery('', 'AutoClear')
+    onClose?.()
+  }
+
+  const selectUser = (user: User) => {
+    if (isMultiple) {
+      const isSelected = selectedUsers.some(
+        (selectedUser) => selectedUser.user_id === user.user_id,
+      )
+      const nextValue = isSelected
+        ? selectedUsers.filter(
+            (selectedUser) => selectedUser.user_id !== user.user_id,
+          )
+        : [...selectedUsers, user]
+
+      if (!isValueControlled) setInnerValue(nextValue)
+      onChange?.(nextValue, {
+        option: user,
+        action: isSelected ? 'Remove' : 'Select',
+      })
+      if (!isSelected) onSelect?.(user, { option: user })
+      updateQuery('', 'AutoClear')
+      return
+    }
+
+    const isSelected = selectedUsers.some(
+      (selectedUser) => selectedUser.user_id === user.user_id,
+    )
+    const nextValue = isSelected ? undefined : user
+
+    if (!isValueControlled) setInnerValue(nextValue)
+    onChange?.(nextValue, {
+      option: user,
+      action: isSelected ? 'Remove' : 'Select',
+    })
+    if (!isSelected) onSelect?.(user, { option: user })
+    closePanel()
+  }
+
+  const selectActiveOption = () => {
+    if (activeIndex < 0) return
+
+    if (onSelectRecordCreator && activeIndex === 0) {
+      onSelectRecordCreator()
+      closePanel()
+      return
+    }
+
+    const userIndex = activeIndex - (onSelectRecordCreator ? 1 : 0)
+    const user = users[userIndex]
+    if (user) selectUser(user)
+  }
+
+  const handleKeyDown: KeyboardEventHandler<HTMLInputElement> = (event) => {
+    onKeyDown?.(event)
+    if (event.defaultPrevented) return
+    if (isKeyboardEventComposing(event)) return
+
+    if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+      event.preventDefault()
+      if (optionCount === 0) return
+      const direction = event.key === 'ArrowDown' ? 1 : -1
+      setActiveIndex((index) => {
+        if (index < 0) return direction > 0 ? 0 : optionCount - 1
+        return (index + direction + optionCount) % optionCount
+      })
+      return
+    }
+
+    if (event.key === 'Enter' && optionCount > 0 && activeIndex >= 0) {
+      event.preventDefault()
+      selectActiveOption()
+    }
+  }
+
+  const renderAvatar = (user: User) => {
+    const avatarUrl = user.avatar.avatar_72 || user.avatar.avatar_240
+
+    return (
+      <span className="relative mr-2 flex size-8 shrink-0 items-center justify-center overflow-hidden rounded-full bg-[#e8f0fe] text-xs leading-none font-medium text-[#1456f0]">
+        {user.name.slice(0, 2)}
+        {avatarUrl ? (
+          <img
+            alt=""
+            className="absolute inset-0 size-full object-cover"
+            onError={(event) => {
+              event.currentTarget.hidden = true
+            }}
+            src={avatarUrl}
+          />
+        ) : null}
+      </span>
+    )
+  }
+
+  return (
+    <div
+      className={cn(
+        'flex w-full flex-col overflow-hidden rounded-md border border-[#dee0e3] bg-white shadow-[0_8px_16px_rgb(31_35_41_/_10%)]',
+        isEmpty && 'py-0.5',
+      )}
+      style={{
+        height: isEmpty ? undefined : 314,
+      }}
+    >
+      <input
+        aria-activedescendant={activeOptionId}
+        aria-autocomplete="list"
+        aria-controls={generatedListboxId}
+        className={cn(
+          'h-9 w-full shrink-0 border-0 border-b border-[rgb(31_35_41_/_15%)] px-3 !text-[14px] !leading-[normal] text-[#1f2329] outline-none placeholder:!text-[#8f959e]',
+          isEmpty && 'h-8 border-b-0 px-[11px]',
+        )}
+        maxLength={50}
+        id={`${generatedListboxId}-search`}
+        name="user-search"
+        onChange={(event) => updateQuery(event.target.value, 'Input')}
+        onCompositionEnd={(event) => {
+          setIsComposing(false)
+          updateQuery(event.currentTarget.value, 'Input')
+        }}
+        onCompositionStart={() => setIsComposing(true)}
+        onKeyDown={handleKeyDown}
+        placeholder="搜索成员"
+        ref={inputRef}
+        role="searchbox"
+        value={query}
+      />
+
+      <div
+        aria-label="成员列表"
+        aria-multiselectable={isMultiple || undefined}
+        className={cn(
+          'flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto px-1 py-1 [scrollbar-color:#bbbfc4_transparent] [scrollbar-width:thin] [&::-webkit-scrollbar-thumb]:rounded-full [&::-webkit-scrollbar-thumb]:border [&::-webkit-scrollbar-thumb]:border-transparent [&::-webkit-scrollbar-thumb]:bg-[#bbbfc4] [&::-webkit-scrollbar-thumb]:bg-clip-padding [&::-webkit-scrollbar]:w-2',
+          isEmpty && 'relative flex-none gap-0 overflow-hidden px-0 py-0',
+          isEmpty &&
+            "pt-[7px] before:absolute before:top-[3px] before:right-0 before:left-0 before:h-px before:bg-[rgb(31_35_41_/_15%)] before:content-['']",
+        )}
+        id={generatedListboxId}
+        role="listbox"
+      >
+        {onSelectRecordCreator ? (
+          <button
+            aria-selected={false}
+            className={cn(
+              'flex h-12 w-full shrink-0 items-center rounded border-0 bg-transparent px-2 text-left text-sm leading-[22px] text-[#1f2329] hover:!bg-[rgb(31_35_41_/_8%)]',
+              activeIndex === 0 && '!bg-[rgb(31_35_41_/_8%)]',
+            )}
+            id={`${generatedListboxId}-option-0`}
+            onClick={() => {
+              onSelectRecordCreator()
+              closePanel()
+            }}
+            onMouseEnter={() => setActiveIndex(0)}
+            role="option"
+            type="button"
+          >
+            <img
+              alt=""
+              className="mr-2 size-8 shrink-0 rounded-full object-cover"
+              src={RECORD_CREATOR_AVATAR_URL}
+            />
+            <span className="min-w-0 flex-1 truncate">添加此记录的人员</span>
+            <span aria-hidden="true" className="ml-[5px] size-3 shrink-0" />
+          </button>
+        ) : null}
+
+        {users.map((user, index) => {
+          const optionIndex = index + (onSelectRecordCreator ? 1 : 0)
+          const selected = selectedUsers.some(
+            (selectedUser) => selectedUser.user_id === user.user_id,
+          )
+          const description =
+            getUserDescription?.(user) || user.description || user.user_id
+
+          return (
+            <button
+              aria-selected={selected}
+              className={cn(
+                'flex h-12 w-full shrink-0 items-center rounded border-0 bg-transparent px-2 text-left text-[#1f2329] hover:!bg-[rgb(31_35_41_/_8%)]',
+                activeIndex === optionIndex && '!bg-[rgb(31_35_41_/_8%)]',
+              )}
+              id={`${generatedListboxId}-option-${optionIndex}`}
+              key={user.user_id}
+              onClick={() => selectUser(user)}
+              onMouseEnter={() => setActiveIndex(optionIndex)}
+              role="option"
+              type="button"
+            >
+              {renderAvatar(user)}
+              <span className="flex min-w-0 flex-1 flex-col justify-center overflow-hidden">
+                <span className="block truncate text-sm leading-[22px] text-[#1f2329]">
+                  {user.name}
+                </span>
+                <span className="block truncate text-xs leading-5 text-[#8f959e]">
+                  {description}
+                </span>
+              </span>
+              <span
+                aria-hidden="true"
+                className="ml-[5px] flex h-5 w-3 shrink-0 items-center text-[#1456f0]"
+              >
+                {selected ? (
+                  <svg className="block size-3" fill="none" viewBox="0 0 24 24">
+                    <path
+                      d="M4 11.293a1 1 0 0 1 1.414 0l4.072 4.07 9.07-9.07a1 1 0 0 1 1.415 0l.706.707a1 1 0 0 1 0 1.414L10.193 18.9a1 1 0 0 1-1.415 0l-5.485-5.485a1 1 0 0 1 0-1.414L4 11.293Z"
+                      fill="currentColor"
+                    />
+                  </svg>
+                ) : null}
+              </span>
+            </button>
+          )
+        })}
+
+        {loading && users.length === 0 ? (
+          <div
+            className="flex min-h-0 flex-1 items-center justify-center"
+            role="status"
+          >
+            <span className="user-selector-loading-spinner flex size-6 text-[#0066ff]">
+              <svg
+                aria-hidden="true"
+                className="size-full"
+                fill="none"
+                viewBox="0 0 100 100"
+              >
+                <circle
+                  cx="50"
+                  cy="50"
+                  r="35"
+                  stroke="currentColor"
+                  strokeLinecap="round"
+                  strokeMiterlimit="10"
+                  strokeWidth="11"
+                />
+              </svg>
+            </span>
+            <span className="sr-only">加载中...</span>
+          </div>
+        ) : null}
+        {isEmpty ? (
+          <div className="flex h-[54px] w-full items-center px-[3px] py-px">
+            <div className="flex h-[52px] w-full min-w-0 items-center overflow-hidden rounded py-1 pr-7 pl-2 text-sm leading-[22px] font-normal text-ellipsis whitespace-nowrap text-[#1f2329] [font-family:'PingFang_SC',system-ui,sans-serif]">
+              {error
+                ? error
+                : query.trim()
+                  ? '没有匹配结果，换个关键词试试吧'
+                  : '暂无推荐成员'}
+            </div>
+          </div>
+        ) : null}
+      </div>
+    </div>
+  )
+}
+
+function normalizeSearchUsersResponse(value: unknown): SearchUsersData {
+  if (!isRecord(value) || typeof value.code !== 'number') {
+    throw new Error('搜索用户返回结构不正确')
+  }
+
+  if (value.code !== 0) {
+    throw new Error(
+      typeof value.msg === 'string' && value.msg ? value.msg : '搜索成员失败',
+    )
+  }
+
+  if (!isRecord(value.data) || !Array.isArray(value.data.users)) {
+    throw new Error('搜索用户返回结构不正确')
+  }
+
+  return {
+    users: value.data.users as User[],
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+export function isKeyboardEventComposing(event: {
+  keyCode?: number
+  nativeEvent?: { isComposing?: boolean }
+}): boolean {
+  return event.nativeEvent?.isComposing === true || event.keyCode === 229
+}

package/templates/database-starter/page/src/components/UserSelectorPanel/user-search.test.ts

@@ -0,0 +1,175 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const projectMeta = vi.hoisted(() => ({ fetchProjectMeta: vi.fn() }))
+const runtime = vi.hoisted(() => ({ fetch: vi.fn() }))
+
+vi.mock('../floating-button/utils/project-meta', () => projectMeta)
+vi.mock('../../lib/database-runtime', () => runtime)
+
+import { normalizeRecommendUsersResponse, requestUsers } from './user-search'
+
+const recommendPayload = {
+  entities: {
+    users: {
+      '6882577547121393684': {
+        avatar_url: 'https://example.com/ada.png',
+        cn_name: '艾达',
+        department: '研究部',
+        en_name: 'Ada',
+        id: '6882577547121393684',
+        i18n_department: { en_us: 'Research', zh_cn: '研究部' },
+        is_external: false,
+      },
+      '6882577547121393685': {
+        avatar_url: 'https://example.com/grace.png',
+        cn_name: '格蕾丝',
+        department: '外部组织',
+        en_name: 'Grace',
+        id: '6882577547121393685',
+        i18n_tenant: { en_us: 'External tenant', zh_cn: '外部租户' },
+        is_external: true,
+      },
+    },
+  },
+  result_list: [
+    { token: '6882577547121393685', type: 0 },
+    { token: 'ignored-chat', type: 1 },
+    { token: '6882577547121393684', type: 0 },
+  ],
+}
+
+beforeEach(() => {
+  runtime.fetch.mockReset()
+  vi.stubGlobal('document', {
+    documentElement: { lang: 'zh-CN' },
+  })
+  projectMeta.fetchProjectMeta.mockReset()
+  projectMeta.fetchProjectMeta.mockResolvedValue({
+    baseBindings: [{ baseToken: 'bascnDemo', tableIds: ['tblDemo'] }],
+  })
+})
+
+describe('requestUsers', () => {
+  it('uses the same Channel Runtime fetch path as GetInvokeProject', async () => {
+    runtime.fetch.mockResolvedValue(
+      new Response(JSON.stringify(recommendPayload), { status: 200 }),
+    )
+
+    const response = await requestUsers('')
+
+    expect(response.data.users.map((user) => user.user_id)).toEqual([
+      '6882577547121393685',
+      '6882577547121393684',
+    ])
+    expect(runtime.fetch).toHaveBeenCalledTimes(1)
+    const [url, init] = runtime.fetch.mock.calls[0] ?? []
+    expect(url).toBe('/space/api/mention/recommend.v2/')
+    expect(init).toMatchObject({
+      headers: {
+        'content-type': 'application/x-www-form-urlencoded',
+      },
+      method: 'POST',
+    })
+    expect(Object.fromEntries(new URLSearchParams(init.body))).toEqual({
+      config_source: '0',
+      obj_type: '8',
+      source: '4',
+      token: 'bascnDemo',
+      type: '0',
+      user_type: '0',
+      content: '',
+    })
+  })
+
+  it('trims the keyword and limits it to 50 characters', async () => {
+    runtime.fetch.mockResolvedValue(
+      new Response(JSON.stringify(recommendPayload), { status: 200 }),
+    )
+
+    await requestUsers(`  ${'a'.repeat(60)}  `)
+
+    const [, init] = runtime.fetch.mock.calls[0] ?? []
+    const body = new URLSearchParams(init.body)
+    expect(body.get('content')).toBe('a'.repeat(50))
+  })
+
+  it('fails before transport when the Site has no bound Base', async () => {
+    projectMeta.fetchProjectMeta.mockResolvedValue({ baseBindings: [] })
+
+    await expect(requestUsers('ada')).rejects.toThrow('应用未绑定 Base')
+    expect(runtime.fetch).not.toHaveBeenCalled()
+  })
+
+  it('reports an HTTP failure without attempting to parse the body', async () => {
+    runtime.fetch.mockResolvedValue(new Response('', { status: 503 }))
+
+    await expect(requestUsers('ada')).rejects.toThrow('HTTP 状态码：503')
+  })
+})
+
+describe('normalizeRecommendUsersResponse', () => {
+  it('keeps recommendation order and maps localized names and descriptions', () => {
+    const result = normalizeRecommendUsersResponse(recommendPayload, 'en-US')
+
+    expect(result.users).toEqual([
+      expect.objectContaining({
+        description: 'External tenant',
+        is_external: true,
+        name: 'Grace',
+        user_id: '6882577547121393685',
+      }),
+      expect.objectContaining({
+        description: 'Research',
+        is_external: false,
+        name: 'Ada',
+        user_id: '6882577547121393684',
+      }),
+    ])
+    expect(result.users[0]?.avatar.avatar_72).toBe(
+      'https://example.com/grace.png',
+    )
+    expect(result.users[0]?.open_id).toBeUndefined()
+  })
+
+  it('prefers an explicit internal user_id and only preserves a real open_id', () => {
+    const result = normalizeRecommendUsersResponse(
+      {
+        entities: {
+          users: {
+            token_ada: {
+              id: 'legacy-id',
+              user_id: '6882577547121393684',
+              open_id: 'ou_ada',
+              name: 'Ada',
+            },
+          },
+        },
+        result_list: [{ token: 'token_ada', type: 0 }],
+      },
+      'en-US',
+    )
+
+    expect(result.users).toEqual([
+      expect.objectContaining({
+        name: 'Ada',
+        open_id: 'ou_ada',
+        user_id: '6882577547121393684',
+      }),
+    ])
+  })
+
+  it('accepts a common response envelope', () => {
+    expect(
+      normalizeRecommendUsersResponse(
+        { code: 0, data: recommendPayload, msg: 'ok' },
+        'zh-CN',
+      ).users.map((user) => user.name),
+    ).toEqual(['格蕾丝', '艾达'])
+  })
+
+  it('surfaces backend business errors', () => {
+    expect(() =>
+      normalizeRecommendUsersResponse({ code: 123, msg: '无权限' }),
+    ).toThrow('无权限')
+  })
+})