Add warning for stale version of documentation

[alisinabh]

Continuation of #1918 (could not push to the same branch since I'm not a maintainer)

---

Based on feedback in #1918 here is the revised version of warning color and icon added when an outdated version is detected.

@halostatue I tried yellow but I could not make it work on Light mode. It would end-up look green-ish when lightness was reduced.

Screenshots

NOTE: Initially I wanted to put the icon after the version, but the <select> HTML element width is set to the largest possible item. This will create an unwanted padding that looks ugly in projects which have versions like 1.2.3-RC0.

[halostatue]

[halostatue]

I think that this should be both more SR friendly and mobile friendly with the use of a popover. I am thinking:

Suggested change

	{{#if latestVersion}}
	<i class="ri-alert-line sidebar-staleIcon" aria-hidden="true"></i>
	{{/if}}
	<select class="sidebar-projectVersionsDropdown{{#if latestVersion}} sidebar-staleVersion{{/if}}"{{#if latestVersion}} title="This version is not the latest version of the package."{{/if}}>
	{{#if latestVersion}}
	<i class="ri-alert-line sidebar-staleIcon" aria-hidden=true popovertarget="staleVersion"></i>
	<span class="sr-only">This is not the latest version of this package.</span>
	<div id="staleVersion" popover>This is not the latest version of this package.</div>
	{{/if}}
	<select class="sidebar-projectVersionsDropdown{{# if latestVersion}} sidebar-staleVersion{{/if}}">

I’m not sure if this will work, though.

[alisinabh]

Since popover works with clicks and not hover, this won't work as clicking on the icon will open the version selector.

[alisinabh]

SR text addressed in da05c1d

[github-actions]

📦 Docs artifacts are ready: https://github.com/elixir-lang/ex_doc/actions/runs/12696202796/artifacts/2408936173

[josevalim]

Sorry, a couple additional thoughts (we are going in circles here and I apologize):

1. The most likely thing the user will want to do is to jump to latest

2. Both --orange and --orangeDark today in light mode today have low AA accessibility rating on Firefox

So my suggestion is:

1. have --orangeDark be hsl(30, 90%, 40%) and use it on light mode
2. have --orangeLight be hsl(30, 80%, 50%) and use it on dark mode
3. Add a link to jump to latest

Here is a quick HTML I came up with:

<div style="display: inline;padding-left: 8px;color: hsl(30, 90%, 40%);">
  <i aria-hidden="true" class="ri-alert-line"></i> <span>Go to latest</span>
</div>

And here is how it looks like:

WDYT?

[halostatue]

Sorry, a couple additional thoughts (we are going in circles here and I apologize):

1. The most likely thing the user will want to do is to jump to latest
2. Both --orange and --orangeDark today in light mode today have low AA accessibility rating on Firefox

So my suggestion is:

1. have --orangeDark be hsl(30, 90%, 40%) and use it on light mode
2. have --orangeLight be hsl(30, 80%, 50%) and use it on dark mode
3. Add a link to jump to latest

You mean something like this?

<div class="sidebar-projectVersion" translate="no">
  <form autocomplete="off">
    <label>
      <span class="sidebar-projectVersionsDropdownCaret" aria-hidden="true">▼</span>
      <span class="sr-only">Project version</span>
      <select class="sidebar-projectVersionsDropdown">
          <option translate="no" value="https://hexdocs.pm/elixir/1.18.1">v1.18.1</option>
          <option translate="no" value="https://hexdocs.pm/elixir/1.18.0">v1.18.0</option>
          <option translate="no" value="https://hexdocs.pm/elixir/1.18.0-rc.0">v1.18.0-rc.0</option>
          <option translate="no" value="https://hexdocs.pm/elixir/1.17.3">v1.17.3</option>
      </select>
    </label>
  </form>
  <div style="display: inline;padding-left: 8px;color: hsl(30, 90%, 40%);">
    <i aria-hidden="true" class="ri-alert-line"></i> <span>Go to latest</span>
  </div>
</div>

[halostatue]

FWIW, I can't seem to get it to work well on Safari with anything except beneath the select or form (so the inline can go away).

[josevalim]

Unfortunately it needs to after the version dropdown, otherwise will break the logo positioning in several designs.

[josevalim]

I understand the issue. The width of the select is dictated by its largest option, since we have options with -rc1, there is extra padding. We would need to use some JavaScript to adjust it. Here is what ChatGPT proposed:

    const adjustWidth = () => {
      // Create a temporary element to measure the width
      const temp = document.createElement('span');
      temp.style.visibility = 'hidden';
      temp.style.position = 'absolute';
      temp.style.whiteSpace = 'nowrap';
      temp.style.font = window.getComputedStyle(select).font;
      temp.textContent = select.options[select.selectedIndex].text;

      document.body.appendChild(temp);
      select.style.width = `${temp.offsetWidth + 20}px`; // Add some padding
      document.body.removeChild(temp);
    };

But I didn't try it. We could run this before we inject the select.

[josevalim]

I tested it on iOS and it worked well, so we are good with going this route. However I have found two bugs:

1. The select has font-weight of 400 but the text currently does not have
2. Clicking on the caret does not open up the select, perhaps we should move the caret inside the text?

[alisinabh]

@josevalim Sorry I was testing my solution and realized it does not work on Safari (needs two clicks since safari does not allow showPicker in some conditions). Tried what you posted and it worked better also the logic is more simple.

Can you please test again?

[josevalim]

@alisinabh I have dropped two last comments and this is good to go! Please rebase the PR and submit it so it doesn't contain changes the formatter directory. Thank you so much! ❤️

[alisinabh]

@josevalim Thank you. Rebased and ready to go.

@halostatue Thanks for your help and input :)

Final screenshots

[josevalim]

💚 💙 💜 💛 ❤️

[wojtekmach]

handleVersionSelected makes sure that when we are on, say, https://hexdocs.pm/elixir/1.18.0/Task.html and from version selector we choose v1.18.1, we'll end up at https://hexdocs.pm/elixir/1.18.1/Task.html.

I think it'd be nice for "Go to latest" to work similarly, preserve relative path.

I'm not very well versed in JS but this is a PoC (copy pasting the implementation with minor changes) for this functionality:

diff --git a/assets/js/sidebar/sidebar-version-select.js b/assets/js/sidebar/sidebar-version-select.js
index 48968c88..de80813f 100644
--- a/assets/js/sidebar/sidebar-version-select.js
+++ b/assets/js/sidebar/sidebar-version-select.js
@@ -34,6 +34,9 @@ if (!isEmbedded) {
     const select = qs(VERSIONS_DROPDOWN_SELECTOR)
     select.addEventListener('change', handleVersionSelected)
     adjustWidth(select)
+
+    const versionsGoToLatest = qs(".sidebar-staleVersion a")
+    versionsGoToLatest.addEventListener('click', handleGoToLatestClicked)
   }
 }

@@ -67,6 +70,22 @@ function handleVersionSelected (event) {
     })
 }

+function handleGoToLatestClicked (event) {
+  const url = this.href
+  const pathSuffix = window.location.pathname.split('/').pop() + window.location.hash
+  const otherVersionWithPath = `${url}/${pathSuffix}`
+  event.preventDefault();
+
+  checkUrlExists(otherVersionWithPath)
+    .then(exists => {
+      if (exists) {
+        window.location.href = otherVersionWithPath
+      } else {
+        window.location.href = url
+      }
+    })
+}

@alisinabh if this piques your interest perhaps you could send another PR?