Skip to content

Conversation

mrjo118
Copy link
Contributor

@mrjo118 mrjo118 commented Sep 27, 2025

As mentioned in this thread https://discourse.joplinapp.org/t/one-enhancement-request-for-syncing/47337, on Joplin desktop, the 'sync as you type' behaviour has a 15 second delay between making a change and the sync automatically running. This is to reduce data usage and avoid distracting the user by having the sync icon constantly stop and start spinning. However, this does mean that if the user abruptly quits the app, there may be un-synced changes which could lead to conflicts. In order to help prevent this from happening for this reason and various other reasons, I have added an indicator which shows whenever there are un-synced (pending) changes, as per a suggestion in the thread. This takes the form of a dot on the right side of the sync button text. Dots are commonly used in apps in many different ways to indicate a current status, an update or a dirty state. This particular presentation is inspired by the dirty state indicator of modified files in VS Code, as what is essentially being represented is a dirty state of the Joplin client with regards to sync items. Using this implementation also makes it easy to blend with any Joplin theme in use, due to using the existing colour of the sync button content.

The dot indicator appears whenever a change is made (which schedules a sync in 15 seconds on desktop, or 1 second on mobile) and also whenever the sync completes (whether success / failure / cancelled) if there are still un-synced outgoing changes. The dot indicator is removed completely while the sync is in progress. I have ensured there is no change in the vertical and horizontal alignment when the dot indicator becomes visible, with the exception of the horizontal alignment on the desktop app (which was difficult due to the horizontal centering of the button contents), but in this case the change in alignment I have kept to a minimum and it is barely noticeable.

Justification

While this was originally intended to help with dealing with potential un-synced items due to the 15 second sync delay on Joplin desktop, the change is also useful for other scenarios and benefits the mobile app as well. There are number of uncommon scenarios within the Synchronizer logic whereby outgoing changes do not get synced, yet the synchronizer reports a successful sync, rather than showing an error. In most cases this will be due to temporary network issues, or simply syncing during a period of an internet outage, which results in a generic network error that is not reported to the UI. But in a couple of cases it can be more terminal issue such as a server being down or remote items having a modified date which is in the future. In these cases, it is beneficial to have the dot indicator as a non intrusive warning sign that something might be wrong with the server or the user's profile, if the dot indicator still persists after multiple automatic or manual syncs.

Limitations

When starting Joplin, the indicator will only appear after the first sync runs, but this will happen automatically within a few seconds of opening the app

Testing

Screenshot on desktop:
dot

Screenshot on mobile:
dotmobile

Video of main tests on desktop:
https://github.com/user-attachments/assets/51c65d9c-9a9a-4a5e-b72f-a354d5d7c5ab

Video of basic test on mobile:
https://github.com/user-attachments/assets/1ce5fe8c-7871-4ba7-920d-a2d5f9ec66ed

Test cases verified:

  1. When the sync target is set to none, the dot indicator should never appear when changes are made
  2. When the sync target is set but not authenticated, the dot indicator should appear when changes are made, but it should not clear the dot until the sync actually runs
  3. When sync is set up and working, when any change triggering a sync is made (eg. change note body, rename notebook, trash note, permanently delete note), this should make the dot indicator appear and it should clear when the sync triggers
  4. When the sync completes, regardless of whether it succeeded or failed, or the prior state of the dot indicator, if there are un-synced outgoing changes remaining on completion, the dot indicator should appear on completion. I tested this by deleting everything in the target directing using file system sync in order to trigger a fail-safe error when there is pending change. I also verified the dot indicator does not appear if there are no pending changes to sync when getting a fail-safe error
  5. When switching the sync target while the dot indicator is visible, the dot indicator should be removed
  6. I have ensured screen readers ignore the dot indicator. On the desktop app I verified the aria-label is set on the button in the html source, and on mobile I verified the bullet point in the button label is ignored when the button is read with TalkBack

@mrjo118 mrjo118 changed the title Desktop, Mobile: Add indicator when there are pending outgoing changes to be synced Desktop, Mobile: Implement a dirty state indicator which shows when there are pending outgoing changes to be synced Sep 27, 2025
@tomasz1986
Copy link

How about adding a tooltip on hover with an explanation? To be honest, I don't think I would know what the dot means if I was just an average user and didn't follow the development of the feature. 😅

@mrjo118
Copy link
Contributor Author

mrjo118 commented Sep 27, 2025

How about adding a tooltip on hover with an explanation? To be honest, I don't think I would know what the dot means if I was just an average user and didn't follow the development of the feature. 😅

Nice suggestion. On desktop I've now added a tooltip which says 'Not all changes have been synced' when the indicator is present. On mobile you can't really add a tooltip, but to be honest for the average user I wouldn't expect them to see the indicator in most cases (due to the short sync delay and the side bar is hidden unless you open it on the main screen), unless they carefully check the sync is completed all the time. But if the indicator persists then it probably is a good time for the user to turn to the forum for support anyway, if they don't know how to diagnose sync issues themselves.

@laurent22
Copy link
Owner

I wonder if there should be a wider discussion with users regarding this change. Your reasoning makes sense but I'm not sure we really want to have this dot there.

@mrjo118
Copy link
Contributor Author

mrjo118 commented Oct 9, 2025

I wonder if there should be a wider discussion with users regarding this change. Your reasoning makes sense but I'm not sure we really want to have this dot there.

@laurent22 What about if we add a configuration setting for this? Maybe under Synchronisation, add a setting called 'Show indicator when not all changes are synced' just below the sync interval setting.
Default it to on, but can be turned off by the user if not wanted

@mrjo118
Copy link
Contributor Author

mrjo118 commented Oct 10, 2025

I wonder if there should be a wider discussion with users regarding this change. Your reasoning makes sense but I'm not sure we really want to have this dot there.

@laurent22 What about if we add a configuration setting for this? Maybe under Synchronisation, add a setting called 'Show indicator when not all changes are synced' just below the sync interval setting. Default it to on, but can be turned off by the user if not wanted

@laurent22 I've updated the PR as described. Let me know what you think

setting

If it is specifically it being a dot that you think is too vague, a potential alternative might be to use an up arrow, maybe like this?:

arrow

This would be similar to common UI's for syncing to remote repositories with version control. It won't support showing an arrow down for when there are incoming changes as well, but then neither will Git detect incoming changes unless you do a fetch

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.

4 participants