Skip to content

docs(diffs): Document editable line annotations - #1003

Merged
amadeus merged 3 commits into
beta-1.3from
amadeus/annotation-documentation
Jul 21, 2026
Merged

docs(diffs): Document editable line annotations#1003
amadeus merged 3 commits into
beta-1.3from
amadeus/annotation-documentation

Conversation

@amadeus

@amadeus amadeus commented Jul 19, 2026

Copy link
Copy Markdown
Member

Most a bunch of additional docs for how to handle line annotations when editing.

  • Document how to manage edit-mode line annotation updates across Editor, CodeView, React, vanilla, and virtualized surfaces.
    • Add examples for synchronizing remapped annotations, committing edited content, updating CodeView versions, and preserving application state with stable metadata IDs.
  • Clarify annotation remapping, deletion, undo/redo, file-level annotations, and annotation content lifecycle behavior.
  • Correct Editor and CodeView callback types to support both LineAnnotation[] and DiffLineAnnotation[].
    • Before it was annotated always as DiffLineAnnotation[] which was technically not accurate
    • Add annotation and collection type guards to make the APIs with ambiguity easier.
  • Add regression coverage for annotation guards, CodeView forwarding, and final-line deletion semantics.

@vercel

vercel Bot commented Jul 19, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
pierre-docs-diffs Ready Ready Preview Jul 21, 2026 12:55am
pierre-docs-diffshub Ready Ready Preview Jul 21, 2026 12:55am
pierre-docs-trees Ready Ready Preview Jul 21, 2026 12:55am
1 Skipped Deployment
Project Deployment Actions Updated (UTC)
pierrejs-diff-demo Skipped Skipped Jul 21, 2026 12:55am

Request Review

@amadeus

amadeus commented Jul 19, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 👍

Reviewed commit: 73da2eec9a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

amadeus added 2 commits July 20, 2026 17:33
Explain how applications retain remapped annotations across
standalone editors and CodeView, including React and vanilla ownership
patterns.

Add typed examples for file and diff annotations, document deletion and
virtualization behavior, and lock final-line deletion semantics with
focused regression tests.
Edit a standalone file with annotations: onChange delivers side-less
LineAnnotation entries, but its public type only allowed DiffLineAnnotation.
CodeView exposed the same mismatch for file items.

Accept the two homogeneous annotation collections throughout Editor and
CodeView, export guards for narrowing them, and update examples and tests
to preserve remapped annotations for either item type.
@amadeus
amadeus force-pushed the amadeus/annotation-documentation branch from 8238e44 to d7c476d Compare July 21, 2026 00:34
@amadeus

amadeus commented Jul 21, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d7c476d16c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread apps/docs/app/(diffs)/docs/Editor/constants.ts Outdated
@vercel
vercel Bot temporarily deployed to Preview – pierrejs-diff-demo July 21, 2026 00:54 Inactive
@amadeus

amadeus commented Jul 21, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit: f590c13643

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@amadeus
amadeus merged commit 88b09b2 into beta-1.3 Jul 21, 2026
8 checks passed
@amadeus
amadeus deleted the amadeus/annotation-documentation branch July 21, 2026 01:04
amadeus added a commit that referenced this pull request Jul 21, 2026
* docs(diffs): Document editable line annotations

Explain how applications retain remapped annotations across
standalone editors and CodeView, including React and vanilla ownership
patterns.

Add typed examples for file and diff annotations, document deletion and
virtualization behavior, and lock final-line deletion semantics with
focused regression tests.

* fix(diffs): Type edit callbacks for file annotations

Edit a standalone file with annotations: onChange delivers side-less
LineAnnotation entries, but its public type only allowed DiffLineAnnotation.
CodeView exposed the same mismatch for file items.

Accept the two homogeneous annotation collections throughout Editor and
CodeView, export guards for narrowing them, and update examples and tests
to preserve remapped annotations for either item type.

* PR Review Fixes
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