Skip to content

Click peer avatar to scroll to that collaborator's caret in docs#188

Merged
hackerwins merged 9 commits into
mainfrom
feat/docs-peer-jump
May 5, 2026
Merged

Click peer avatar to scroll to that collaborator's caret in docs#188
hackerwins merged 9 commits into
mainfrom
feat/docs-peer-jump

Conversation

@hackerwins

@hackerwins hackerwins commented May 5, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Clicking a peer's avatar in the docs SiteHeader smooth-scrolls the editor so that collaborator's caret sits roughly one-third from the top of the viewport.
  • Generalises the shared UserPresence component (used by Sheets too) to a domain-agnostic onSelectPeer(clientID) + getJumpHint(clientID) API. Sheets call sites are migrated as a pure refactor — no behavioural change.
  • Adds a domain-agnostic EditorAPI.scrollToPosition(pos: DocPosition) to @wafflebase/docs that reuses the existing resolvePositionPixel helper.
  • Only the viewport scrolls — the local caret is unaffected, which avoids interrupting typing flow.

Design: docs/design/docs/docs-peer-jump.md
Implementation plan / lessons: archived under docs/tasks/archive/2026/05/.

Test plan

pnpm verify:fast (lint + typecheck + 741 unit tests) is green on every commit.

Two-browser smoke checklist (open the same docs document in two windows signed in as different users):

  • Hover a peer avatar after the peer has typed → tooltip reads Click to jump to {username}.
  • Click the avatar → smooth scroll lands the peer caret at roughly the top one-third of the viewport, peer label is visible for ~4s.
  • Local caret stays put (typing right after the scroll continues at the original local cursor).
  • Avatar disabled when the peer has not broadcast activeCursorPos yet (tooltip shows only username).
  • Self-click disabled.
  • Sheets regression: peer-jump in a multi-tab spreadsheet still switches tabs and selects the peer's cell.
  • Mobile zoom-to-fit (devtools narrow viewport): peer-jump scrolls to the correct Y.

Notes

  • SharedDocsLayout (read-only shared docs view) still passes a bare <UserPresence /> and is not wired for peer-jump in this PR — flagged as a follow-up in the lessons file.

🤖 Generated with Claude Code

hackerwins and others added 9 commits May 5, 2026 21:10
Design for clicking a collaborator's avatar in the docs SiteHeader to
smooth-scroll the editor so the peer's caret is visible. Mirrors the
Sheets click-to-jump UX but only scrolls — the local caret stays put,
which avoids interrupting typing flow in the docs editor.

The change also generalises the shared UserPresence component so it
no longer carries Sheets-specific prop names. Sheets call sites get a
pure refactor with no behavioural change.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Bite-sized task breakdown for the spec at
docs/design/docs/docs-peer-jump.md: five tasks covering the new
EditorAPI.scrollToPosition method, UserPresence generalisation +
Sheets migration, DocsView jump handle, DocsLayout wiring, and
manual verification + archive.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Domain-agnostic helper that smooth-scrolls the viewport so a given
DocPosition appears roughly one-third from the top. Reuses the
existing resolvePositionPixel helper that backs peer cursor rendering
and Cmd+F result jumps. Silent no-op before the first paint or when
the blockId is stale.

Caches canvasHeight and logicalCanvasWidth in initialize() closure
scope so the new method can read them outside the render pipeline.
UserPresence no longer knows about Sheets-specific activeCell. The
component now emits a domain-agnostic onSelectPeer(clientID) event
and asks the host for a tooltip hint via getJumpHint(clientID). This
is the precondition for wiring docs peer-jump in a follow-up commit.

Sheets call sites in document-detail.tsx and shared-document.tsx are
migrated to the new API. Each picks up the click, looks up the peer
in Yorkie presence, and runs the same tab-resolution + peer-jump-
target logic as before. Pure refactor — no behavioural change.
Pull the duplicated hint/canJump computation out of renderAvatar and
the +N dropdown into a tiny resolveHint helper so the pattern lives
in one place. Replace onSelectPeer!() non-null assertions with an
explicit early return that lets TypeScript narrow the prop. Pure
refactor — no behavioural change.
DocsView gains a jumpToPeer(clientID) callback that resolves the
peer's activeCursorPos from Yorkie presence and asks the editor to
scrollToPosition there. Also resets the 4-second peer-label timer so
the username briefly re-appears at the landing position.

The handle is published via a new optional onJumpHandleReady prop;
no consumer wires it up in this commit.
The prop comment claimed 'peer-jump, scroll' but the JumpHandle
exposes only jumpToPeer. Drop the misleading 'scroll' clause.
DocsLayout now holds a JumpHandle from DocsView and forwards peer
avatar clicks through it. getJumpHint reads the peer's username from
DocsPresence and gates the click affordance on activeCursorPos being
present. Only the viewport scrolls — the local caret is unaffected.
Manual verification deferred to PR review (recorded in the lessons
file). All five plan tasks shipped behind pnpm verify:fast green
across each commit.
@coderabbitai

coderabbitai Bot commented May 5, 2026

Copy link
Copy Markdown

Warning

Rate limit exceeded

@hackerwins has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 58 minutes and 46 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ec4757c3-f9e1-47db-bbf1-056c467bd914

📥 Commits

Reviewing files that changed from the base of the PR and between 39ce058 and 389e635.

📒 Files selected for processing (12)
  • docs/design/README.md
  • docs/design/docs/docs-peer-jump.md
  • docs/tasks/README.md
  • docs/tasks/archive/2026/05/20260505-docs-peer-jump-lessons.md
  • docs/tasks/archive/2026/05/20260505-docs-peer-jump-todo.md
  • docs/tasks/archive/README.md
  • packages/docs/src/view/editor.ts
  • packages/frontend/src/app/docs/docs-detail.tsx
  • packages/frontend/src/app/docs/docs-view.tsx
  • packages/frontend/src/app/documents/document-detail.tsx
  • packages/frontend/src/app/shared/shared-document.tsx
  • packages/frontend/src/components/user-presence.tsx
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/docs-peer-jump

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions

github-actions Bot commented May 5, 2026

Copy link
Copy Markdown
Contributor

Verification: verify:self

Result: ✅ PASS in 143.8s

Lane Status Duration
sheets:build ✅ pass 13.7s
docs:build ✅ pass 12.6s
verify:fast ✅ pass 73.9s
frontend:build ✅ pass 18.0s
verify:frontend:chunks ✅ pass 0.3s
backend:build ✅ pass 5.0s
cli:build ✅ pass 2.1s
verify:entropy ✅ pass 18.0s

Verification: verify:integration

Result: ✅ PASS

@codecov

codecov Bot commented May 5, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 0% with 21 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
packages/docs/src/view/editor.ts 0.00% 21 Missing ⚠️

📢 Thoughts on this report? Let us know!

@hackerwins
hackerwins merged commit 0f1a35d into main May 5, 2026
4 checks passed
@hackerwins
hackerwins deleted the feat/docs-peer-jump branch May 5, 2026 13:43
@hackerwins hackerwins mentioned this pull request May 11, 2026
6 tasks
hackerwins added a commit that referenced this pull request May 11, 2026
Adds @wafflebase/slides as a third surface alongside Sheets and Docs,
plus 53-shape library (Phase 1+2), adjustment handles for 9 pilot
shapes (P3-A.1), live snap guides, align/distribute toolbar, themed
authoring, and layout-change UI. Also ships Sheets cell comments
(Phase B), docs peer-avatar caret jump, yorkie-js-sdk 0.7.8 upgrade,
and CLI/REST API improvements (docs export imageFetcher, expired
session refresh, REST docs split). Minor bump because slides is a
new top-level package.

Highlights: #184 #185 #186 #187 #188 #189 #190 #191 #192 #197 #198
#201 #202 #203 #204 #205 #206 #207 #209 #210
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant