In release notes web view, allow de-emphasizing past releases

[Cykelero]

The problem

In the Sparkle feed of the app I'm developing, the releaseNotesLink HTML includes the notes of all released versions, not just the latest one. This way, if someone hasn't updated the app in a while, when they get the update prompt, they can scroll down and see all that's been changed since the version they're running.

However: it's not immediately clear what's new, and what's not. All releases are displayed the same: both the releasers newer than what the user is running, and the ones that are older.
I'd love to improve on that. For instance, I could gray out the notes of the currently installed version, and all notes before that.

It's currently not possible, as far as I can tell, because the HTML document is not aware of the user's currently installed version. I'd like to add support for exposing that data in Sparkle.

Proposed solution

Sparkle could inject a CSS variable in the web view, specifying the currently installed version; something like --sparkle-installed-app-version: "2.5.2".

• Developers could consume the variable with JavaScript (see example below), and hopefully/eventually, as CSS evolves, with only CSS.
• With a specific enough name, the variable wouldn't interfere with any existing release notes content, and so wouldn't need opt-in from the developer.
• Additional values could be injected (both build number and human-readable version; why not macOS version if user opted in to analytics, etc) either right now, or in a later change.

Usage example

Imagining release notes that looks like this:

<article data-release="2.6.0">
	<h1>Version 2.6.0</h1>
	Adds gizmos.
</article>

<article data-release="2.5.2">
	<h1>Version 2.5.2</h1>
	Fixes doodads.
</article>

<article data-release="2.5.1">
	<h1>Version 2.5.1</h1>
	Fixes whatnots.
</article>

Then the version variable could be consumed like this:

<style>
	article.current, article.current ~ article {
		opacity: 0.5;
	}
</style>

<script>
	const installedAppVersion = getComputedStyle(document.body).getPropertyValue("--sparkle-installed-app-version");
	const installedAppVersionElement = document.querySelector(`[data-release=${installedAppVersion}]`);
	installedAppVersionElement.classList.add("current");
</script>

With this result:

(To run the example yourself, add the variable definition—which Sparkle would inject—in the script tag: document.body.style.setProperty("--sparkle-installed-app-version", "\"2.5.2\"");)

Alternative solution

Sparkle could go a bit further, and actually set a class on an element automatically. For instance, it could look for all elements with a data property matching the current version, and add a sparkle-current CSS class on them.
This solution would be less flexible, but require less work on the developer's part (no boilerplate JS glue to rewrite) and be more secure (no need to enable JS in the Web View.

An example of using this solution is simply reusing the code above, just without the <script> tag at all.

Notes

If this feels like a good fit for Sparkle, I'll be happy to contribute (my best go at) an implementation!

I think I prefer the second solution (less boilerplate, no need to enable JS), myself; but I wonder if the first one might be more in line with Sparkle's project goals (less prescriptive).
Both could very well be implemented, actually, letting the developer choose how to adopt.

[zorgiepoo]

Today we allow a developer to set custom HTTP headers which will get passed to the feed, update download, and release notes. So it should theoretically be possible for you to pass the app version, have your server parse the version and generate the release notes accordingly. It does probably require some server-side logic though.

CSS, or styling, doesn't feel like the right approach to me. Some developers may want to strip out all release notes the user has already seen <= current, instead of stylizing older or non-current items differently.

There may also be merit in being html-agnostic. For example we'd like to support (basic) Markdown one day, and we support plain-text today. We also would like to avoid adding enhancements that encourage enabling Javascript which rules out the first proposal.

By the way, I don't think I understand your example. Let's say current version in your example is 2.5.2. So sparkle-current is added to that, but how does that also affect 2.5.1 since you'd want to stylize both versions the same way. edit: Never mind, I see the CSS style is clever: article.current, article.current ~ article

[zorgiepoo]

On second thought, maybe this type of enhancement would still have its place since it requires no server-side configuration. How it would work with WKWebView is that you probably have to insert a user script / javascript to set the sparkle-current.. and do something.. (Javascript is only disabled from the web content but still available on Sparkle's end I think).

[zorgiepoo]

So your example could potentially be:

<!-- Developer writes this style -->
<style>
	article.current-release-version, article.current-release-version ~ article {
		opacity: 0.5;
	}
</style>

<!-- Sparkle inserts this script -->
<script>
	const installedVersionElement = document.querySelector(`[data-release-version=$SPARKLE_WILL_INSERT_THIS_VERSION_DIRECTLY]`);
        if (installedVersionElement !== null) {
	    installedVersionElement.classList.add("current-release-version");
        }
</script>

[Cykelero]

Sounds perfect! Adding a class on matching elements would still leave a lot of flexibility, and wouldn't especially force developers' hands, or break existing notes. I'll try my hand at an implementation and submit a PR.

Of note:

• JavaScript doesn't seem to have access to response headers for the document; so as you said, currently, the only possible implementation for devs is through server-side code (which somewhat rules out delivering all Sparkle content through a CDN).
• Maybe it's obvious, but although somewhat inefficient, you could very well use display: none with this class-based approach, to only show relevant updates. This is probably what I'll end up doing myself!