@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/collab/collab-presence-header.tsx

@@ -0,0 +1,220 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 编辑器头部在线头像组（任务 18，规格 §7.1 知识库行「头部在线头像组 +
+// N 人正在编辑」）。照 sharers-avatar-group 模式（UserAvatar + AvatarGroup
+// + tooltip + 折叠 +N）。
+//
+// 数据源 = 文档 room 的 provider awareness 远端 states（同一 provider
+// handle，见 CollabDocGate → useCollabDoc）。每个远端 state 的身份字段：
+//   - `profile`（本组件广播）：USER_BRIEF 口径 {id, username, avatarConfig,
+//     bgShape, bgColor}——email 明确剔除（awareness 对房间内所有人可见）。
+//   - `user`（CollaborationCaret 写入）：仅 {name, color}——profile 未落地
+//     时（瞬态/引导失败）降级用名字渲染首字母头像，身份键取 `caret:{name}`。
+// 远端 state 不可信，逐份 fail-closed 校验（畸形丢弃，同 presence-store 口径）。
+//
+// 自身排除双口径：profile.id === selfId（常态），caret 名字 === selfName
+// （profile 广播前的瞬态窗口）。同用户多 tab（同 id 多 client）按 id 去重。
+//
+// noop/降级（handle 或 awareness 为 null）与无远端协作者 → 渲染 null，
+// 不占头部空间。
+
+import { useEffect, useState } from 'react'
+import { UserAvatar } from '@/components/shared-kit'
+import {
+  AvatarGroup,
+  AvatarGroupTooltip,
+} from '@/components/magicui/components/animate/avatar-group'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { cn } from '@/lib/utils'
+import type { AvatarConfig } from '@allbluecn/kernel'
+import type { CollabAwareness, CollabProviderHandle } from '@/lib/collab/provider'
+import { useSelfProfileBroadcast, type CollabPresenceUser } from '@/lib/collab/use-self-profile-broadcast'
+import { m } from '@/paraglide/messages.js'
+
+export type { CollabPresenceUser } from '@/lib/collab/use-self-profile-broadcast'
+
+export interface CollabPresenceHeaderProps {
+  /** room 连接句柄（null = 非协同分支；awareness null = noop 降级）→ 均渲染 null */
+  handle: CollabProviderHandle | null
+  /** 当前用户 id（excludeSelf 常态口径） */
+  selfId?: string | null
+  /** 当前用户显示名（caret 瞬态窗口的 excludeSelf 兜底；同 CollabDocGate 的 caret 名） */
+  selfName?: string | null
+  /** 折叠前最多展示的头像数（超出 +N） */
+  max?: number
+}
+
+// ---------------------------------------------------------------------------
+// 远端 state 解析（fail-closed）
+// ---------------------------------------------------------------------------
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/** kernel AvatarConfig 形态校验（Record<string, number>，同 presence-store） */
+function isAvatarConfig(value: unknown): value is Record<string, number> {
+  return (
+    isRecord(value) && Object.values(value).every((v) => typeof v === 'number')
+  )
+}
+
+function parseProfile(raw: unknown): CollabPresenceUser | null {
+  if (!isRecord(raw)) return null
+  if (typeof raw.id !== 'string' || raw.id.length === 0) return null
+  if (typeof raw.username !== 'string') return null
+  const user: CollabPresenceUser = { id: raw.id, username: raw.username }
+  if (isAvatarConfig(raw.avatarConfig)) user.avatarConfig = raw.avatarConfig
+  if (typeof raw.bgShape === 'string') user.bgShape = raw.bgShape
+  if (typeof raw.bgColor === 'string') user.bgColor = raw.bgColor
+  return user
+}
+
+/**
+ * 解析一份 awareness state 为在线协作者：优先 profile 字段，降级 caret
+ * user.name（身份键 caret:{name}）。畸形 state 返回 null（调用方丢弃）。
+ */
+export function parseCollaboratorState(raw: unknown): CollabPresenceUser | null {
+  if (!isRecord(raw)) return null
+  const profile = parseProfile(raw.profile)
+  if (profile) return profile
+  if (isRecord(raw.user) && typeof raw.user.name === 'string' && raw.user.name) {
+    return { id: `caret:${raw.user.name}`, username: raw.user.name }
+  }
+  return null
+}/**
+ * 收集远端协作者：排除自己（id / caret 名字双口径）、同 id 去重（多 tab
+ * 一人），保持 awareness states 插入序。
+ */
+export function collectRemoteCollaborators(
+  states: Iterable<readonly [number, unknown]>,
+  selfId?: string | null,
+  selfName?: string | null,
+): CollabPresenceUser[] {
+  const byId = new Map<string, CollabPresenceUser>()
+  for (const [, raw] of states) {
+    const user = parseCollaboratorState(raw)
+    if (!user) continue
+    const isCaretFallback = user.id.startsWith('caret:')
+    if (!isCaretFallback && user.id === selfId) continue
+    if (isCaretFallback && selfName && user.username === selfName) continue
+    if (byId.has(user.id)) continue
+    byId.set(user.id, user)
+  }
+  return [...byId.values()]
+}
+
+// ---------------------------------------------------------------------------
+// awareness 订阅 hook
+// ---------------------------------------------------------------------------
+
+function useRemoteCollaborators(
+  awareness: CollabAwareness | null,
+  selfId?: string | null,
+  selfName?: string | null,
+): CollabPresenceUser[] {
+  const [list, setList] = useState<CollabPresenceUser[]>(() =>
+    awareness
+      ? collectRemoteCollaborators(awareness.getStates().entries(), selfId, selfName)
+      : [],
+  )
+  useEffect(() => {
+    if (!awareness) {
+      setList([])
+      return
+    }
+    const sync = () =>
+      setList(collectRemoteCollaborators(awareness.getStates().entries(), selfId, selfName))
+    sync()
+    awareness.on('update', sync)
+    return () => {
+      awareness.off('update', sync)
+    }
+  }, [awareness, selfId, selfName])
+  return list
+}
+
+// ---------------------------------------------------------------------------
+// 组件
+// ---------------------------------------------------------------------------
+
+export function CollabPresenceHeader({
+  handle,
+  selfId,
+  selfName,
+  max = 5,
+}: CollabPresenceHeaderProps) {
+  const awareness = handle?.awareness ?? null
+  const collaborators = useRemoteCollaborators(awareness, selfId, selfName)
+  useSelfProfileBroadcast(handle)
+
+  if (!awareness || collaborators.length === 0) return null
+
+  const shown = collaborators.slice(0, max)
+  const rest = Math.max(0, collaborators.length - max)
+
+  return (
+    <div
+      data-testid="collab-presence-header"
+      className="flex items-center gap-2"
+    >
+      <div className="flex items-center -space-x-2">
+        <AvatarGroup className="h-6 -space-x-2" invertOverlap translate="-22%" sideOffset={14}>
+          {shown.map((user) => (
+            <div key={user.id} className="ring-2 ring-background rounded-full">
+              <UserAvatar
+                name={user.username}
+                avatarConfig={(user.avatarConfig ?? null) as AvatarConfig | null}
+                bgShape={user.bgShape}
+                bgColor={user.bgColor ?? undefined}
+                size="sm"
+              />
+              <AvatarGroupTooltip>
+                {m.collab_presenceTooltip({ name: user.username })}
+              </AvatarGroupTooltip>
+            </div>
+          ))}
+        </AvatarGroup>
+        {rest > 0 && (
+          <Tooltip>
+            <TooltipTrigger
+              render={
+                <div
+                  className={cn(
+                    'flex h-6 w-6 items-center justify-center rounded-full bg-muted text-[10px] font-medium ring-2 ring-background cursor-default',
+                  )}
+                />
+              }
+            >
+              +{rest}
+            </TooltipTrigger>
+            <TooltipContent>
+              {m.collab_presenceEditingCount({ count: collaborators.length })}
+            </TooltipContent>
+          </Tooltip>
+        )}
+      </div>
+      <span
+        data-testid="collab-presence-count"
+        className="text-xs text-muted-foreground whitespace-nowrap"
+      >
+        {m.collab_presenceEditingCount({ count: collaborators.length })}
+      </span>
+    </div>
+  )
+}

package/src/components/collab/entity-presence-badge.tsx

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 列表行/卡片在看成员徽标（任务 24，§7.1 列表行「行/卡片上远端在看的人
+// 头像（hover 名单）」）。照 PresenceAvatarStack 模式（UserAvatar +
+// Tooltip + +N 折叠）轻量实现；挂载在列表行组件内（行根需带 `group`
+// class），默认透明、行 hover 渐显（无在看者渲染 null 不占位）。
+//
+// 数据源 = presence-store 全局在场（列表页不建连实体 room，性能红线），
+// 按 module + route 精确匹配在看者：route 是剥 query 的实体详情纯路径
+// （/stories/{id} 等，§8.1），比 entityTitle 标题匹配更稳（防重复标题
+// 误配）；entityTitle（详情页标题）当前无上报方，行 tooltip 固定
+// 「正在查看此条目」，不依赖它。
+//
+// excludeSelf：session 口径 selfId 排除本人（§8.2，同侧边栏头像组）。
+
+import { useMemo } from "react";
+import { UserAvatar } from "@/components/shared-kit";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
+import type { AvatarConfig } from "@allbluecn/kernel";
+import { useSession } from "@/lib/auth/auth-client";
+import {
+  arePresenceListsContentEqual,
+  useTeammates,
+} from "@/lib/collab/presence-store";
+import type { PresenceState } from "@/lib/collab/presence-store";
+import { cn } from "@/lib/utils";
+import { m } from "@/paraglide/messages.js";
+
+/** 展开态最多直接展示的头像数，超出折叠 +N */
+const MAX_VISIBLE = 3;
+
+export interface EntityPresenceBadgeProps {
+  /** 一级模块 key（§8.1，如 stories/bugs/test-cases） */
+  module: string;
+  /** 实体详情纯路径（如 /stories/{id}，presence route 同口径） */
+  route: string;
+  /** 折叠前最多展示的头像数（超出 +N） */
+  max?: number;
+  className?: string;
+}
+
+/** 按模块 + 实体路由过滤在看者的 selector（useMemo 保持 identity 稳定） */
+function useEntityViewers(module: string, route: string, selfId?: string | null): PresenceState[] {
+  const selector = useMemo(
+    () =>
+      (list: PresenceState[]) =>
+        list.filter((state) => state.module === module && state.route === route),
+    [module, route],
+  );
+  // 内容级 compare（忽略 ts）：心跳式全量重建不重渲染行组件（审查重要①，
+  // per-row 订阅同理——每行一份 selector，N 行 × 心跳的空转必须为零）
+  return useTeammates(selector, selfId, arePresenceListsContentEqual);
+}
+
+export function EntityPresenceBadge({
+  module,
+  route,
+  max = MAX_VISIBLE,
+  className,
+}: EntityPresenceBadgeProps) {
+  const { data: session } = useSession();
+  const viewers = useEntityViewers(module, route, session?.user?.id ?? null);
+
+  // 无在看者不占位（§8.2「不显示」降级口径）
+  if (viewers.length === 0) return null;
+  const shown = viewers.slice(0, max);
+  const rest = viewers.length - shown.length;
+
+  return (
+    <div
+      data-testid="entity-presence-badge"
+      className={cn(
+        "flex shrink-0 items-center opacity-0 transition-opacity group-hover:opacity-100",
+        className,
+      )}
+    >
+      <div className="flex items-center -space-x-1.5">
+        {shown.map((state) => (
+          <Tooltip key={state.user.id}>
+            <TooltipTrigger
+              render={
+                <div className="cursor-default rounded-full ring-2 ring-background">
+                  <UserAvatar
+                    name={state.user.username}
+                    avatarConfig={state.user.avatarConfig as AvatarConfig | null | undefined}
+                    bgShape={state.user.bgShape}
+                    bgColor={state.user.bgColor ?? undefined}
+                    size="xs"
+                  />
+                </div>
+              }
+            />
+            <TooltipContent>
+              {m.presence_row_tooltipEntry({ name: state.user.username })}
+            </TooltipContent>
+          </Tooltip>
+        ))}
+        {rest > 0 && (
+          <Tooltip>
+            <TooltipTrigger
+              render={
+                <div className="flex h-5 w-5 cursor-default items-center justify-center rounded-full bg-muted text-[10px] font-medium ring-2 ring-background">
+                  +{rest}
+                </div>
+              }
+            />
+            <TooltipContent>
+              {m.presence_row_overflowCount({ count: rest })}
+            </TooltipContent>
+          </Tooltip>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/collab/field-editing-pill.tsx

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 字段旁「X 正在编辑」头像 pill（Yjs 多人协作 §7.1 字段型行 / §10.1 实时
+// 来源，任务 20）。数据源 = useCollabFields 的 editingBy（room awareness
+// 的 `editing:{fieldName}` ephemeral 标记，远端即时到达；自身不在内）。
+//
+// 3s 余晖（§10.1「字段 blur 后保留 3s 余晖」）：远端 blur 摘标记后 editingBy
+// 变空，pill 不立即消失，保留最后一批编辑者 3s 再撤——避免「刚看到就消失」
+// 的闪烁；期间远端重新开编（标记重写）则无缝续显。实现为防抖清除（Pacer
+// useDebouncedCallback，3000ms；非空到达即 cancel），非轮询、非定时器直写。
+//
+// 头像：编辑者 userId 在 users（UserBrief 列表，详情页 loader 已取）内查到
+// 则带 NotionAvatar/底色渲染，查不到降级首字母头像（编辑者署名缺省或名单
+// 未含协作者时）。noop 降级（editors 恒空）与无标记 → 渲染 null 不占空间。
+
+import { useEffect, useRef, useState } from "react";
+import { useDebouncer } from "@/lib/pacer";
+import { UserAvatar } from "@/components/shared-kit";
+import type { AvatarConfig } from "@allbluecn/kernel";
+import { m } from "@/paraglide/messages.js";
+import type { FieldEditorInfo } from "@/lib/collab/bindings/fields";
+
+/** 余晖时长（规格 §10.1：blur 后保留 3s） */
+export const FIELD_PILL_LINGER_MS = 3000;
+
+export interface FieldEditingPillProps {
+  /** pill 锚定的字段名（仅用于 data-testid 定位，不参与渲染） */
+  fieldName: string;
+  /** 远端编辑者列表（useCollabFields().editingBy[fieldName]，ts 新者在前） */
+  editors: FieldEditorInfo[] | undefined;
+  /** 成员名单（头像渲染用；详情页 users prop 直传） */
+  users?: Array<{
+    id: string;
+    username: string;
+    avatarConfig?: unknown;
+    bgShape?: string | null;
+    bgColor?: string | null;
+  }>;
+  /** 余晖时长（默认 3000ms；测试可注入更短值） */
+  lingerMs?: number;
+  /** 折叠前最多展示的头像数（超出并入「N 人正在编辑」计数） */
+  max?: number;
+}
+
+/** 余晖窗内的兜底空列表（引用稳定，避免无关 re-render） */
+const EMPTY_EDITORS: FieldEditorInfo[] = [];
+
+export function FieldEditingPill({
+  fieldName,
+  editors,
+  users,
+  lingerMs = FIELD_PILL_LINGER_MS,
+  max = 3,
+}: FieldEditingPillProps) {
+  // 余晖态（§10.1「blur 后保留 3s 余晖」）：远端标记在位时跟随 editors 实时
+  // 渲染；变空后进入余晖窗——继续显示最后一批编辑者（lastLiveRef），3s 后
+  // 撤除。期间远端重新开编（标记重写，hasLive 回真）则 cancel 无缝续显。
+  // 用 useDebouncer 承载 3s 撤除（含 cancel；useDebouncedCallback 不暴露
+  // 实例方法）。
+  const lastLiveRef = useRef<FieldEditorInfo[]>(EMPTY_EDITORS);
+  const [lingering, setLingering] = useState(false);
+  const hasLive = !!editors && editors.length > 0;
+  if (hasLive && editors) lastLiveRef.current = editors; // 渲染期跟随最新名单
+
+  const lingerRef = useRef(setLingering);
+  lingerRef.current = setLingering;
+  const clearLinger = useDebouncer(
+    () => lingerRef.current(false),
+    { wait: lingerMs },
+  );
+
+  useEffect(() => {
+    if (hasLive) {
+      clearLinger.cancel();
+      setLingering(false);
+    } else if (lastLiveRef.current.length > 0) {
+      // 变空瞬间进入余晖窗；期间标记重写（hasLive 回真）会被 cancel
+      setLingering(true);
+      clearLinger.maybeExecute();
+    }
+  }, [hasLive, clearLinger]);
+
+  const shown = hasLive ? editors! : lingering ? lastLiveRef.current : EMPTY_EDITORS;
+  if (shown.length === 0) return null;
+
+  const visible = shown.slice(0, max);
+  const rest = Math.max(0, shown.length - max);
+  const firstName = visible[0]!.name || visible[0]!.userId;
+
+  return (
+    <div
+      data-testid={`collab-field-pill-${fieldName}`}
+      data-state={hasLive ? "live" : "linger"}
+      className="flex items-center gap-1 rounded-full border bg-muted/40 py-0.5 pr-2 pl-0.5"
+    >
+      <div className="flex items-center -space-x-1.5">
+        {visible.map((editor) => {
+          const user = users?.find((u) => u.id === editor.userId);
+          return (
+            <UserAvatar
+              key={editor.clientId}
+              name={user?.username ?? (editor.name || editor.userId)}
+              avatarConfig={(user?.avatarConfig ?? null) as AvatarConfig | null}
+              bgShape={user?.bgShape ?? "circle"}
+              bgColor={user?.bgColor ?? undefined}
+              size="xs"
+              className="!w-4.5 !h-4.5 ring-1 ring-background"
+            />
+          );
+        })}
+      </div>
+      <span className="text-xs whitespace-nowrap text-muted-foreground">
+        {shown.length === 1
+          ? m.collab_fieldEditingBy({ name: firstName })
+          : m.collab_presenceEditingCount({ count: shown.length })}
+      </span>
+      {rest > 0 && (
+        <span className="text-xs text-muted-foreground">+{rest}</span>
+      )}
+    </div>
+  );
+}

package/src/components/command/command-palette.tsx

@@ -16,8 +16,8 @@
 // along with this program. If nosee <https://www.gnu.org/licenses/>.
 
 import { useState, useSyncExternalStore } from "react"
-import { useTheme } from "next-themes"
-import { useHotkey, useHotkeySequences } from "@tanstack/react-hotkeys"
+import { useThemeMode } from "@/providers/theme-mode-provider"
+import { useHotkey, useHotkeys } from "@tanstack/react-hotkeys"
 import type { HotkeySequence } from "@tanstack/hotkeys"
 import {
   CommandMenu,
@@ -81,7 +81,7 @@ const PALETTE_ICON_MAP: Record<string, LucideIcon> = {
 }
 
 export function CommandPalette() {
-  const { theme, setTheme } = useTheme()
+  const { toggle } = useThemeMode()
   const [designDialogOpen, setDesignDialogOpen] = useState(false)
 
   const open = useSyncExternalStore(
@@ -111,16 +111,16 @@ export function CommandPalette() {
       // FS-5.4：设计画布编辑器内 Mod+Shift+L 是「锁定」命令（canvas useEditCommands），
       // 全局主题切换在画布挂载时让位，避免双 handler 同时触发（锁定同时翻转主题）
       if (document.querySelector('[data-testid="canvas-viewport"]')) return
-      setTheme(theme === "dark" ? "light" : "dark")
+      toggle()
     },
     { ignoreInputs: false },
   )
 
-  useHotkeySequences(
+  useHotkeys(
     commands
       .filter((c) => c.shortcut && c.shortcut.length >= 2)
       .map((c) => ({
-        sequence: c.shortcut as HotkeySequence,
+        hotkey: c.shortcut as HotkeySequence,
         callback: () => run(c),
         options: { enabled: !open },
       })),