Skip to content

diff: Report the character under the pointer so a diff can host links - #4042

Merged
huacnlee merged 1 commit into
longbridge:mainfrom
sassman:diff-text-pointer-pr
Nov 20, 2026
Merged

huacnlee merged 1 commit into
longbridge:mainfrom
sassman:diff-text-pointer-pr

Conversation

@sassman

@sassman sassman commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Purpose

Closes #4040. Diff reports pointer interaction at line granularity, so an application cannot tell which character — and therefore which word — the pointer is over. That rules out the link idiom every code surface has: Cmd/Ctrl-hover marks a symbol, an issue reference or a file path, Cmd/Ctrl-click follows it. This PR adds character-level pointer events while keeping the component semantics-free: it reports positions, the application decides what they mean.

diffie-symbol-navigation-v2.mov

What changed

  • on_text_hover reports the character under the pointer with the held modifiers, or None off the text, and only on change. While the diff has focus it also fires when a modifier goes down or up with the pointer at rest, so a link can light up on the key alone.
  • on_text_click hears a click on a character before on_line_click; returning true claims the click. text_cursor sets the pointer shown over source text.
  • DiffTextPosition carries the line position, the character's byte offset in the line's content (the unit span-highlight spans use) and the line's text, so the handler can read the word around the offset without a copy of the patch.
  • DiffSpanHighlight can underline in its text color (with_underline), and a fully transparent with_background leaves the line showing through, so the hovered span reads as a link rather than a search match.
  • DiffState::has_line says whether the patch carries a line, so the application knows whether a jump target is in the diff before scrolling.
  • Hit testing reuses the painted-run geometry the text selection already keeps; past a line's end is over no character, and a run clipped by horizontal scrolling is not hit under its clip.
  • Site docs (en, zh-CN) and five window tests: hover reporting and change-only delivery, modifier-at-rest delivery, claimed and unclaimed clicks, has_line over folded and absent lines.

Public API

gpui-component

pub struct DiffTextPosition { /* private */ }
impl DiffTextPosition {
    pub fn position(&self) -> &DiffLinePosition;  // the line the character is on
    pub fn offset(&self) -> usize;                // byte offset in the line's content
    pub fn text(&self) -> &SharedString;          // the line's content
}

impl Diff {
    pub fn on_text_hover<F>(self, handler: F) -> Self
    where F: Fn(Option<&DiffTextPosition>, Modifiers, &mut Window, &mut App) + 'static;
    pub fn on_text_click<F>(self, handler: F) -> Self
    where F: Fn(&DiffTextPosition, &ClickEvent, &mut Window, &mut App) -> bool + 'static;
    pub fn text_cursor(self, cursor: CursorStyle) -> Self;
}

impl DiffSpanHighlight {
    pub fn with_underline(self) -> Self;  // underline in the text color
}

impl DiffState {
    /// Whether the patch carries the source line, shown or folded.
    pub fn has_line(&self, position: &DiffLinePosition) -> bool;
}

No existing item changes; no breaking changes.

Validation

cargo test -p gpui-component diff tests pass (69, five new), cargo fmt --check and cargo clippy -p gpui-component are clean on the touched files, typos clean. Exercised end to end in a GPUI Kit review application: Cmd-hover underlines a resolvable symbol, Cmd-click jumps to its definition, plain clicks still select text and lines.

This change was written with AI assistance (implementation and tests), reviewed and exercised by a human-driven application.

@huacnlee

Copy link
Copy Markdown
Member

💡 Needs the maintainer's call on the API shape: the capability is useful, but the public surface is larger than the use case needs.

Reviewed at 7b1b60d. cargo test -p gpui-component --lib diff: 69 passed. No CI checks have run on this branch yet.

New public API (+516/-23):

  • Diff::on_text_hover, Diff::on_text_click, Diff::text_cursor, DiffTextPosition { position(), offset(), text() }
  • DiffSpanHighlight::without_background, with_underline, is_filled, is_underlined
  • DiffState::has_line

Points to consider:

  1. without_background adds a second filled: bool next to the existing background: Option<Hsla>, two ways to express fill; and the project prefers positive options over negations. Something like with_background(transparent) or a single style enum would avoid the parallel flag. is_filled / is_underlined getters are only needed by the renderer and could stay pub(crate).
  2. on_text_click returning bool to claim the click before on_line_click is an implicit priority rule; documenting it or using cx.stop_propagation() style like other gpui handlers would be more familiar.
  3. text_cursor as a separate setter could be folded into the hover handler result or left to the default text cursor unless a concrete need exists.

Code otherwise reads cleanly and the docs (en, zh-CN) are updated.

🤖 Noop (reviewer) · AI agent acting for @huacnlee

@huacnlee

Copy link
Copy Markdown
Member

💡 The direction is welcome; please narrow the public API before we accept it:

  1. Drop without_background: it is a negative flag and duplicates the existing background parameter. Use the existing parameter instead.
  2. Make is_filled / is_underlined non-public (pub(crate) or private); they are only used internally.
  3. Document the click precedence: the per-character handler returning true to pre-empt the line click is not obvious. Please state the rule in the doc comment (or use an explicit stop-propagation style) so callers know which handler wins.

Once these are in, we'll re-review (reviewed head 7b1b60d).

🤖 Noop (reviewer) · AI agent acting for @huacnlee

sassman added a commit to sassman/gpui-kit that referenced this pull request Nov 19, 2026
…eview

Upstream review on longbridge#4042 asked to shrink the public
surface: without_background and is_filled duplicated what a transparent
with_background already expresses, is_underlined is only read by the
renderer, and the text-click precedence over the line handler deserved
stating on both doc comments. Excerpts gained the ordering debug_assert
from the longbridge#4043 review.

Signed-off-by: Sven Kanoldt <sven@d34dl0ck.me>
Diff reports the character under the pointer with the held modifiers
(on_text_hover, also when a modifier changes with the pointer at rest),
hands clicks on a character to on_text_click before the line handler,
and takes a text cursor. Span highlights can be underlined and unfilled,
so the hovered span reads as a link. DiffState::has_line says whether
the patch carries a line, so the application can decide where a jump
lands before scrolling.

Signed-off-by: Sven Kanoldt <sven@d34dl0ck.me>
@sassman
sassman force-pushed the diff-text-pointer-pr branch from 7b1b60d to 749dc8e Compare November 19, 2026 15:47
@huacnlee

Copy link
Copy Markdown
Member

✅ API looks good at 749dc8e. All three points from the previous review are addressed:

  1. without_background is gone; a transparent fill goes through the existing background parameter.
  2. is_filled / is_underlined are no longer public.
  3. on_text_click documents the precedence: the text handler runs first, true claims the click, false falls through to on_line_click.

The remaining public surface (on_text_hover, on_text_click, text_cursor, DiffTextPosition, DiffSpanHighlight::with_underline, DiffState::has_line) is opt-in, additive, and reports positions without adding link semantics to the component, which matches how editors host Cmd/Ctrl-click links. cargo test -p gpui-component --lib diff: 69 passed locally. CI is running now; once it is green this can be merged.

🤖 Noop (rust-maintainer) · AI agent acting for @huacnlee

@sassman

sassman commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Review points addressed at 749dc8e (PR description updated to match):

  1. without_background and is_filled are gone. The no-fill case goes through the existing parameter: a fully transparent with_background leaves the line showing through, and its doc comment says so. Site docs (en, zh-CN) updated.
  2. is_underlined is pub(crate).
  3. The click precedence is stated on both doc comments: on_text_click says the text handler runs first and returning true claims the click, false lets it fall through; on_line_click says a claimed text click does not reach it.

On the red Test Docs check: the failure is org-notes: invalid preview filename from .showcases/scripts/validate.ts during the site build. It reproduces identically on unrelated PRs (e.g. the claude/combobox-free-text run) and comes from the showcase catalog, not this change.

@huacnlee
huacnlee merged commit a9d5371 into longbridge:main Nov 20, 2026
18 of 19 checks passed
linruohan pushed a commit to linruohan/gpui-kit that referenced this pull request Nov 20, 2026
…longbridge#4042)

## Purpose

Closes longbridge#4040. `Diff` reports pointer interaction at line granularity, so
an application cannot tell which character — and therefore which word —
the pointer is over. That rules out the link idiom every code surface
has: Cmd/Ctrl-hover marks a symbol, an issue reference or a file path,
Cmd/Ctrl-click follows it. This PR adds character-level pointer events
while keeping the component semantics-free: it reports positions, the
application decides what they mean.


https://github.com/user-attachments/assets/21acb6b0-6529-4b6b-a0df-7de6a2db43f7

## What changed

- `on_text_hover` reports the character under the pointer with the held
modifiers, or `None` off the text, and only on change. While the diff
has focus it also fires when a modifier goes down or up with the pointer
at rest, so a link can light up on the key alone.
- `on_text_click` hears a click on a character before `on_line_click`;
returning true claims the click. `text_cursor` sets the pointer shown
over source text.
- `DiffTextPosition` carries the line position, the character's byte
offset in the line's content (the unit span-highlight spans use) and the
line's text, so the handler can read the word around the offset without
a copy of the patch.
- `DiffSpanHighlight` can underline in its text color
(`with_underline`), and a fully transparent `with_background` leaves the
line showing through, so the hovered span reads as a link rather than a
search match.
- `DiffState::has_line` says whether the patch carries a line, so the
application knows whether a jump target is in the diff before scrolling.
- Hit testing reuses the painted-run geometry the text selection already
keeps; past a line's end is over no character, and a run clipped by
horizontal scrolling is not hit under its clip.
- Site docs (en, zh-CN) and five window tests: hover reporting and
change-only delivery, modifier-at-rest delivery, claimed and unclaimed
clicks, `has_line` over folded and absent lines.

## Public API

### gpui-component

```rust
pub struct DiffTextPosition { /* private */ }
impl DiffTextPosition {
    pub fn position(&self) -> &DiffLinePosition;  // the line the character is on
    pub fn offset(&self) -> usize;                // byte offset in the line's content
    pub fn text(&self) -> &SharedString;          // the line's content
}

impl Diff {
    pub fn on_text_hover<F>(self, handler: F) -> Self
    where F: Fn(Option<&DiffTextPosition>, Modifiers, &mut Window, &mut App) + 'static;
    pub fn on_text_click<F>(self, handler: F) -> Self
    where F: Fn(&DiffTextPosition, &ClickEvent, &mut Window, &mut App) -> bool + 'static;
    pub fn text_cursor(self, cursor: CursorStyle) -> Self;
}

impl DiffSpanHighlight {
    pub fn with_underline(self) -> Self;  // underline in the text color
}

impl DiffState {
    /// Whether the patch carries the source line, shown or folded.
    pub fn has_line(&self, position: &DiffLinePosition) -> bool;
}
```

No existing item changes; no breaking changes.

## Validation

`cargo test -p gpui-component` diff tests pass (69, five new), `cargo
fmt --check` and `cargo clippy -p gpui-component` are clean on the
touched files, `typos` clean. Exercised end to end in a GPUI Kit review
application: Cmd-hover underlines a resolvable symbol, Cmd-click jumps
to its definition, plain clicks still select text and lines.

This change was written with AI assistance (implementation and tests),
reviewed and exercised by a human-driven application.

Signed-off-by: Sven Kanoldt <sven@d34dl0ck.me>
@sassman
sassman deleted the diff-text-pointer-pr branch November 20, 2026 23:27
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.

diff: The pointer cannot address a character, so a diff cannot host links

2 participants