How-to guides

Display a patch

Pass unified patch text to Diff(patch=patch_text). For multi-file or multi-commit patches, patch_file=0 selects the first file; subsequent indices follow patch order. Create one Diff per index to display several files.

A non-null patch takes precedence over old_file and new_file. Bind patch to null to return to file comparison. Invalid patches or indices produce a visible error and a render-error event.

Partial patches contain only their supplied context. Use complete old/new files when users need to expand omitted lines.

Synchronize selection

Bind the selected range to a transports-hosted model and send user changes to an endpoint:

from spaday import CallEndpoint, event_value
from spaday_diffs import Diff

comparison = (
    Diff(old_file=before, new_file=after)
    .bind("selected_lines", "selected_lines")
    .on(
        "selection-change",
        CallEndpoint("POST", "/api/review/selection", event_value()),
    )
)

The endpoint receives {"range": {"start": 2, "end": 4, "side": "additions"}}. Store that range in the hosted model. Set it to null to clear selection. Programmatic selection updates do not emit another event.

See spaday_diffs/example.py for the model, endpoint, WebSocket route, and autosync setup.

Add review notes

comparison = Diff(
    old_file=before,
    new_file=after,
    annotations=[
        {"side": "additions", "line": 3, "text": "Check this value."},
    ],
)

Lines are one-based. Line 0 adds a file-level note. Annotation text is rendered literally, not interpreted as HTML.

Override colors

comparison.css(
    spa_diffs_surface="#101827",
    spa_diffs_text="#e2e8f0",
    spa_diffs_added="#68d391",
    spa_diffs_deleted="#fc8181",
)

Set theme_type="dark" for dark syntax highlighting. Package tokens inherit from spaday shell tokens; direct overrides apply only to that viewer. Use theme to choose another Shiki syntax theme.

Regenerate Python bindings

After editing the custom-elements manifest:

python -m spaday.cem spaday_diffs/components.cem.json -o spaday_diffs/components.py
python -m ruff format spaday_diffs/components.py

The tests compare generated bindings with the manifest.