Add Dark Mode Option for Documentation Page

[Slanderkin]

I think it would be nice to be able to have a toggle on the documentation page so that you can view it in dark mode, or just have a dark version of the documentation pages.

[falkoschindler]

Good idea, @Slanderkin!
My approach from #342 (comment) might be a starting point.

But we should probably store the user preference in some session data, so that the dark mode is not always reset when the user visits the site again.

[falkoschindler]

@Slanderkin After thinking about it once again: Why should we use a toggle instead of simply setting dark mode to "auto", i.e. automatically setting the theme based on the user's system settings?

[Slanderkin]

That sounds like a good idea, definitely better than the toggle. I'll have to try and see if I can come up with this, not sure when I will get to it though.

[suspiciousRaccoon]

I think the best option would be to emulate something like MDN's docs.

It has os-theme by default in local storage and the user is able to change it to their preference.

[rodja]

Storing user specific data will get much simpler as soon as pull request #967 is merged and released.

[suspiciousRaccoon]

I've come up with this so far. Which kinda works..?

from functools import partial
from nicegui import ui, app


async def manage_darkmode(current_theme, dark):
    if current_theme['theme'] == 'OS-default':
        dark.auto()
    elif current_theme['theme'] == 'Dark':
        dark.enable()
    else:
        dark.disable()
    await ui.run_javascript(f'localStorage.setItem("theme", "{current_theme["theme"]}")', respond=False)


@ui.page("/")
async def index():
    current_theme = {'theme': None}
    dark = ui.dark_mode()
    ui.select(
        ['OS-default', 'Dark', 'Light'], on_change=partial(manage_darkmode, current_theme, dark)).bind_value(current_theme, 'theme')
    app.on_connect(partial(get_local_storage, current_theme, dark))


async def get_local_storage(current_theme, dark):
    current_theme['theme'] = await ui.run_javascript(f'localStorage.getItem("theme");')
    await manage_darkmode(current_theme, dark)


ui.run()

The code can probably be simplified and improved more as well, but I'm still not familiar enough with NiceGUI and Python to know how

[falkoschindler]

With the new storage API (planned for 1.2.17) we can simplify this code quite a bit:

from nicegui import Client, app, ui

@ui.page('/')
async def page(client: Client):
    await client.connected()
    app.storage.user['dark_mode'] = app.storage.user.get('dark_mode', False)
    ui.dark_mode().bind_value(app.storage.user, 'dark_mode')
    ui.toggle({False: 'Light', True: 'Dark', None: 'Auto'}).bind_value(app.storage.user, 'dark_mode')

ui.run(storage_secret='secret')

And we're planning to automatically initialize a dictionary value for missing keys when binding to UI, so the line app.storage.user['dark_mode'] = ... will not be necessary anymore.

Unfortunately there's a short flash of white background before switching to dark mode, because the user storage is only available after the client is connected. We should be able to replace storage.user with storage.browser and get rid of client.connected. But currently the binding module doesn't recognize the ReadOnlyDict as dictionary.

Apart from the theme selection UI, the main challenge is to update the website to support both light and dark mode. If you run main.py with dark=True, the colors are pretty much messed up.

[rodja]

We should be able to replace storage.user with storage.browser and get rid of client.connected. But currently the binding module doesn't recognize the ReadOnlyDict as dictionary.

I've just merged @falkoschindler's fixes from #981. So this is not a concern anymore.

Unfortunately there's a short flash of white background before switching to dark mode, because the user storage is only available after the client is connected.

The user storage is already available before the client connects. Same as browser storage. This is working for me with the main branch:

@ui.page('/')
async def page():
    ui.dark_mode().bind_value(app.storage.user, 'dark_mode')
    ui.toggle({False: 'Light', True: 'Dark', None: 'Auto'}).bind_value(app.storage.user, 'dark_mode')

[falkoschindler]

Indeed, this works! 🙂
But shouldn't app.storage.browser work the same?

[rodja]

Yes, app.storage.browser also works. But in general it's better to use app.storage.user because it is stored on the server.

[rodja]

Ahhh... sorry. I've just tried it. It does not work. And here is why: the browser storage can not be changed after the initial website has been delivered. Because for security reasons we use a http-only cookie.
Normally you'll get an error message if you try to access the browser storage later. For example with this code:

ui.toggle({False: 'Light', True: 'Dark', None: 'Auto'}, on_change=lambda args: app.storage.browser.set('dark_mode', args.value))

But because the binding happens to the writeable dict on construction our access-check in the app.storage.browser property is not triggered.

[falkoschindler]

Oh, sure! That explains it. 👍

[falkoschindler]

I just started to implement this feature in PR #1164.