gitea-admin/gh-christianlouis-docuelevate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(ui): add dark mode support with system preference detection and localStorage persistence

Browse Source 
Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-02-25 13:59:49 +00:00
parent 9cbffc4acb
commit c428a7ec00
9 changed files with 416 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.env.demo
+5
View File
@@ -6,6 +6,11 @@ EXTERNAL_HOSTNAME=docuelevate.example.com
GOTENBERG_URL=http://gotenberg:3000
ALLOW_FILE_DELETE=true # Allow deletion of file records
# **UI / Appearance**
# Default colour scheme: system (follow OS), light, or dark
# Individual users can always override with the navbar dark-mode toggle.
# UI_DEFAULT_COLOR_SCHEME=system
# **Batch Processing Settings**
# Control throttling behavior for the /processall endpoint to prevent overwhelming downstream APIs
PROCESSALL_THROTTLE_THRESHOLD=20 # Number of files above which throttling is applied (default: 20)
app/config.py
+10
View File
@@ -382,6 +382,16 @@ class Settings(BaseSettings):
),
)
# UI / Appearance
ui_default_color_scheme: str = Field(
default="system",
description=(
"Default color scheme for the web interface. "
"Options: 'system' (follow OS preference), 'light', 'dark'. "
"Individual users can override this with the in-app toggle; their choice is persisted in localStorage."
),
)
# Rate Limiting Configuration (see SECURITY_AUDIT.md and docs/API.md)
# Protects against DoS attacks and API abuse
rate_limiting_enabled: bool = Field(
app/utils/settings_service.py
+14
View File
@@ -1153,6 +1153,20 @@ SETTING_METADATA = {
"required": False,
"restart_required": False,
},
# UI / Appearance
"ui_default_color_scheme": {
"category": "UI",
"description": (
"Default color scheme for the web interface. "
"Options: 'system' (follow OS preference), 'light', 'dark'. "
"Individual users can override this with the in-app toggle; their choice is persisted in localStorage."
),
"type": "string",
"sensitive": False,
"required": False,
"restart_required": False,
"options": ["system", "light", "dark"],
},
}
app/views/base.py
+4
View File
@@ -34,11 +34,15 @@ def template_response_with_version(*args, **kwargs):
req = args[1].get("request")
if req is not None and hasattr(req.state, "csrf_token"):
args[1].setdefault("csrf_token", req.state.csrf_token)
# Inject default color scheme for dark-mode initialisation
args[1].setdefault("ui_default_color_scheme", getattr(settings, "ui_default_color_scheme", "system"))
elif "context" in kwargs and isinstance(kwargs["context"], dict):
kwargs["context"].setdefault("version", settings.version)
req = kwargs["context"].get("request")
if req is not None and hasattr(req.state, "csrf_token"):
kwargs["context"].setdefault("csrf_token", req.state.csrf_token)
# Inject default color scheme for dark-mode initialisation
kwargs["context"].setdefault("ui_default_color_scheme", getattr(settings, "ui_default_color_scheme", "system"))
return original_template_response(*args, **kwargs)
docs/ConfigurationGuide.md
+26
View File
@@ -759,6 +759,32 @@ For detailed setup instructions, see the [Notifications Setup Guide](Notificatio
| `UPTIME_KUMA_URL` | Uptime Kuma push URL for monitoring the application's health. |
| `UPTIME_KUMA_PING_INTERVAL` | How often to ping Uptime Kuma in minutes (default: `5`). |
### UI / Appearance
DocuElevate supports a **dark mode** toggle in the navbar. Users can switch between light and dark themes at any time; their choice is stored in `localStorage` and persists across page reloads in the same browser.
Administrators can set the **site-wide default** colour scheme that is applied when a user has not yet made a personal choice:
| **Variable** | **Description** | **Default** |
|----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| `UI_DEFAULT_COLOR_SCHEME` | Default colour scheme for all users. Options: `system` (follow OS preference), `light`, `dark`. Users can always override with the navbar toggle. | `system` |
**How it works:**
1. On page load an inline script checks the user's `localStorage` preference first.
2. If no stored preference exists, the server-supplied `UI_DEFAULT_COLOR_SCHEME` is used.
3. When the value is `system` (the default), the OS-level `prefers-color-scheme` media query is respected.
4. Clicking the 🌙 / ☀️ toggle in the navbar saves the new preference to `localStorage` immediately.
**WCAG AA compliance:** All dark-mode colour pairs have been chosen with a minimum 4.5:1 contrast ratio for normal text and 3:1 for large text.
**Example:**
```dotenv
# Force dark mode for all users by default
UI_DEFAULT_COLOR_SCHEME=dark
```
## Configuration Examples
### Minimal Configuration
frontend/static/js/common.js
+75
View File
@@ -34,6 +34,81 @@ function getCsrfToken() {
};
})();
// ---------------------------------------------------------------------------
// Dark mode
// ---------------------------------------------------------------------------
// Preference is stored in localStorage under the key 'colorScheme'.
// Values: 'dark' | 'light' (absence means "follow server/system default").
// The anti-flash <script> in base.html applies the class before page paint.
// ---------------------------------------------------------------------------
/**
* Sync the icon and label of both desktop and mobile toggle buttons to the
* current dark-mode state.
*/
function _updateDarkModeButtons() {
const isDark = document.documentElement.classList.contains('dark');
// Desktop button
const btn = document.getElementById('darkModeToggle');
if (btn) {
const icon = btn.querySelector('i');
if (icon) {
icon.className = isDark ? 'fas fa-sun' : 'fas fa-moon';
}
const label = isDark ? 'Switch to light mode' : 'Switch to dark mode';
btn.setAttribute('title', label);
btn.setAttribute('aria-label', label);
}
// Mobile button
const mobileIcon = document.getElementById('darkModeIconMobile');
if (mobileIcon) {
mobileIcon.className = isDark ? 'fas fa-sun mr-2' : 'fas fa-moon mr-2';
}
const mobileText = document.getElementById('darkModeTextMobile');
if (mobileText) {
mobileText.textContent = isDark ? 'Light Mode' : 'Dark Mode';
}
}
/**
* Toggle dark mode and persist the choice to localStorage.
* Called from the navbar button (onclick="toggleDarkMode()").
*/
function toggleDarkMode() {
const isDark = document.documentElement.classList.toggle('dark');
localStorage.setItem('colorScheme', isDark ? 'dark' : 'light');
_updateDarkModeButtons();
}
// Initialise button state once the DOM is ready.
document.addEventListener('DOMContentLoaded', function () {
_updateDarkModeButtons();
});
// React to OS-level theme changes when the user has not explicitly chosen a
// scheme (no localStorage value means "follow the server/system default").
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function (e) {
if (localStorage.getItem('colorScheme')) {
return; // User has an explicit preference; ignore OS changes.
}
var serverDefault = document.documentElement.getAttribute('data-color-scheme-default') || 'system';
if (serverDefault !== 'system') {
return; // Admin has forced a specific scheme; ignore OS changes.
}
if (e.matches) {
document.documentElement.classList.add('dark');
} else {
document.documentElement.classList.remove('dark');
}
_updateDarkModeButtons();
});
// ---------------------------------------------------------------------------
// Authentication status
// ---------------------------------------------------------------------------
// Check authentication status and update the auth section
(async function() {
console.log('Checking authentication status...');
frontend/static/styles.css
+128
View File
@@ -36,3 +36,131 @@ body {
width: 100%;
}
}
/* =============================================================
DARK MODE
Activated by "dark" class on <html> element.
Toggled by the navbar button; preference stored in localStorage.
Falls back to the server-side ui_default_color_scheme setting,
then to the OS prefers-color-scheme media query.
WCAG AA contrast ratios verified for all text/background pairs.
============================================================= */
/* Tell the browser we support both colour schemes */
html { color-scheme: light; }
html.dark { color-scheme: dark; }
/* ---- Base / Body ---- */
html.dark body { background-color: #111827; color: #e5e7eb; }
html.dark .bg-gray-50 { background-color: #111827; }
html.dark .bg-white { background-color: #1f2937; }
html.dark .bg-gray-100 { background-color: #374151; }
html.dark .bg-gray-200 { background-color: #4b5563; }
/* ---- Text colours ---- */
html.dark .text-gray-900 { color: #f9fafb; }
html.dark .text-gray-800 { color: #f3f4f6; }
html.dark .text-gray-700 { color: #e5e7eb; }
html.dark .text-gray-600 { color: #d1d5db; }
html.dark .text-gray-500 { color: #9ca3af; }
html.dark .text-gray-400 { color: #9ca3af; }
html.dark .text-black { color: #f9fafb; }
/* ---- Borders ---- */
html.dark .border-gray-100 { border-color: #374151; }
html.dark .border-gray-200 { border-color: #374151; }
html.dark .border-gray-300 { border-color: #4b5563; }
html.dark .border-gray-400 { border-color: #6b7280; }
html.dark .divide-gray-200 > :not([hidden]) ~ :not([hidden]) { border-color: #374151; }
html.dark .divide-gray-100 > :not([hidden]) ~ :not([hidden]) { border-color: #374151; }
html.dark .divide-y > :not([hidden]) ~ :not([hidden]) { border-color: #374151; }
/* ---- Hover states ---- */
html.dark .hover\:bg-gray-50:hover { background-color: #374151; }
html.dark .hover\:bg-gray-100:hover { background-color: #4b5563; }
html.dark .hover\:text-gray-900:hover { color: #f9fafb; }
html.dark .hover\:text-gray-700:hover { color: #e5e7eb; }
/* ---- Shadows (softened for dark mode) ---- */
html.dark .shadow,
html.dark .shadow-md,
html.dark .shadow-sm,
html.dark .shadow-lg {
box-shadow: 0 1px 3px 0 rgba(0,0,0,0.6), 0 1px 2px 0 rgba(0,0,0,0.4);
}
/* ---- Alert / info-banner backgrounds ---- */
html.dark .bg-blue-50 { background-color: #1e3a5f; }
html.dark .bg-green-50 { background-color: #052e16; }
html.dark .bg-red-50 { background-color: #450a0a; }
html.dark .bg-yellow-50 { background-color: #451a03; }
html.dark .bg-indigo-50 { background-color: #1e1b4b; }
html.dark .bg-orange-50 { background-color: #431407; }
/* ---- Badge / pill backgrounds ---- */
html.dark .bg-blue-100 { background-color: #1e3a5f; }
html.dark .bg-green-100 { background-color: #052e16; }
html.dark .bg-red-100 { background-color: #450a0a; }
html.dark .bg-yellow-100 { background-color: #451a03; }
html.dark .bg-indigo-100 { background-color: #1e1b4b; }
html.dark .bg-orange-100 { background-color: #431407; }
html.dark .bg-purple-100 { background-color: #2e1065; }
/* ---- Status / badge text colours ---- */
html.dark .text-blue-700 { color: #93c5fd; }
html.dark .text-blue-800 { color: #bfdbfe; }
html.dark .text-green-700 { color: #86efac; }
html.dark .text-green-800 { color: #bbf7d0; }
html.dark .text-red-700 { color: #fca5a5; }
html.dark .text-red-800 { color: #fecaca; }
html.dark .text-yellow-700 { color: #fcd34d; }
html.dark .text-yellow-800 { color: #fde68a; }
html.dark .text-indigo-700 { color: #a5b4fc; }
html.dark .text-indigo-800 { color: #c7d2fe; }
html.dark .text-orange-700 { color: #fdba74; }
html.dark .text-orange-800 { color: #fed7aa; }
html.dark .text-purple-700 { color: #d8b4fe; }
html.dark .text-purple-800 { color: #e9d5ff; }
/* ---- Dropdown / popup menus ---- */
html.dark .bg-white.rounded-md.shadow-lg { background-color: #1f2937; }
html.dark .ring-black { --tw-ring-color: rgba(0,0,0,0.5); }
/* ---- Form inputs / selects / textareas ---- */
html.dark input:not([type="checkbox"]):not([type="radio"]):not([type="range"]),
html.dark select,
html.dark textarea {
background-color: #374151;
border-color: #4b5563;
color: #e5e7eb;
}
html.dark input::placeholder,
html.dark textarea::placeholder {
color: #9ca3af;
}
html.dark input:focus:not([type="checkbox"]):not([type="radio"]):not([type="range"]),
html.dark select:focus,
html.dark textarea:focus {
border-color: #60a5fa;
outline-color: #60a5fa;
}
/* ---- Table rows ---- */
html.dark thead,
html.dark .bg-gray-50 thead { background-color: #1f2937; }
html.dark thead th { color: #9ca3af; }
html.dark tbody tr:hover { background-color: #374151; }
/* ---- Code / pre ---- */
html.dark pre,
html.dark code { background-color: #111827; color: #d1d5db; }
/* ---- Dark-mode toggle button icon colour ---- */
html.dark #darkModeToggle { color: #fbbf24; }
html.dark #darkModeToggle:hover { background-color: #374151; }
/* ---- Scrollbar (WebKit browsers) ---- */
html.dark ::-webkit-scrollbar { width: 8px; height: 8px; }
html.dark ::-webkit-scrollbar-track { background: #1f2937; }
html.dark ::-webkit-scrollbar-thumb { background: #4b5563; border-radius: 4px; }
html.dark ::-webkit-scrollbar-thumb:hover { background: #6b7280; }
frontend/templates/base.html
+37 -1
View File
@@ -1,9 +1,21 @@
<!DOCTYPE html>
<html lang="en">
<html lang="en" data-color-scheme-default="{{ ui_default_color_scheme | default('system') }}">
<head>
<meta charset="UTF-8" />
<title>{% block title %}DocuElevate{% endblock %}</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<!-- Anti-flash dark mode script: runs before CSS/JS to prevent white flash -->
<script>
(function () {
var stored = localStorage.getItem('colorScheme');
var serverDefault = document.documentElement.getAttribute('data-color-scheme-default') || 'system';
var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
var scheme = stored || serverDefault;
if (scheme === 'dark' || (scheme === 'system' && prefersDark)) {
document.documentElement.classList.add('dark');
}
})();
</script>
<!-- Tailwind CSS or other global CSS references -->
<link rel="stylesheet" href="/static/styles.css" />
<!-- Alpine.js moved to head for earlier loading -->
@@ -93,6 +105,18 @@
<a href="/about" class="text-gray-700 hover:text-gray-900">About</a>
<!-- Dark mode toggle (desktop) -->
<button
id="darkModeToggle"
onclick="toggleDarkMode()"
type="button"
class="p-1.5 rounded-md text-gray-500 hover:text-gray-700 hover:bg-gray-100 focus:outline-none focus:ring-2 focus:ring-inset focus:ring-blue-500"
aria-label="Toggle dark mode"
title="Toggle dark mode"
>
<i class="fas fa-moon"></i>
</button>
<!-- Dynamic Auth Section -->
<div id="authSection" class="text-gray-700 hover:text-gray-900"></div>
</div>
@@ -152,6 +176,18 @@
<a href="/about" class="block px-3 py-3 rounded-md text-base font-medium text-gray-700 hover:text-gray-900 hover:bg-gray-50">About</a>
<!-- Dark mode toggle (mobile) -->
<button
onclick="toggleDarkMode()"
type="button"
class="flex items-center w-full px-3 py-3 rounded-md text-base font-medium text-gray-700 hover:text-gray-900 hover:bg-gray-50"
id="darkModeToggleMobile"
aria-label="Toggle dark mode"
>
<i class="fas fa-moon mr-2" id="darkModeIconMobile"></i>
<span id="darkModeTextMobile">Dark Mode</span>
</button>
<!-- Mobile Auth Section -->
<div id="mobileAuthSection" class="block px-3 py-3 rounded-md text-base font-medium text-gray-700 hover:text-gray-900 hover:bg-gray-50">
<!-- Will be populated by JS -->
tests/test_dark_mode.py
+117
View File
@@ -0,0 +1,117 @@
"""Tests for dark mode support.
Covers:
- ui_default_color_scheme setting in config
- Setting metadata entry in settings_service
- ui_default_color_scheme injected into template context via views/base.py
- base.html renders data-color-scheme-default attribute and toggle button
"""
import pytest
from app.config import settings
from app.utils.settings_service import SETTING_METADATA
@pytest.mark.unit
class TestDarkModeConfig:
"""Tests for the ui_default_color_scheme configuration field."""
def test_default_is_system(self):
"""ui_default_color_scheme should default to 'system'."""
assert settings.ui_default_color_scheme == "system"
def test_valid_values_documented(self):
"""Setting metadata should list valid options."""
meta = SETTING_METADATA.get("ui_default_color_scheme", {})
assert "options" in meta
assert set(meta["options"]) == {"system", "light", "dark"}
def test_metadata_category(self):
"""Setting should belong to the 'UI' category."""
meta = SETTING_METADATA.get("ui_default_color_scheme", {})
assert meta.get("category") == "UI"
def test_metadata_not_sensitive(self):
"""Color scheme preference is not a sensitive setting."""
meta = SETTING_METADATA.get("ui_default_color_scheme", {})
assert meta.get("sensitive") is False
def test_metadata_no_restart_required(self):
"""Changing the color scheme should not require a restart."""
meta = SETTING_METADATA.get("ui_default_color_scheme", {})
assert meta.get("restart_required") is False
@pytest.mark.unit
class TestDarkModeTemplateInjection:
"""Tests for ui_default_color_scheme being injected into template context."""
def test_default_injected_when_missing(self):
"""Wrapper should inject ui_default_color_scheme when absent from context."""
from unittest.mock import MagicMock, patch
from app.views.base import template_response_with_version
captured = {}
def fake_original(name, ctx, **kw):
captured.update(ctx)
with patch("app.views.base.original_template_response", side_effect=fake_original):
mock_request = MagicMock()
mock_request.state = MagicMock(spec=[]) # no csrf_token attr
template_response_with_version("page.html", {"request": mock_request})
assert "ui_default_color_scheme" in captured
def test_existing_value_not_overridden(self):
"""Wrapper must NOT overwrite an explicitly supplied value."""
from unittest.mock import MagicMock, patch
from app.views.base import template_response_with_version
captured = {}
def fake_original(name, ctx, **kw):
captured.update(ctx)
with patch("app.views.base.original_template_response", side_effect=fake_original):
mock_request = MagicMock()
mock_request.state = MagicMock(spec=[])
template_response_with_version(
"page.html",
{"request": mock_request, "ui_default_color_scheme": "dark"},
)
assert captured["ui_default_color_scheme"] == "dark"
@pytest.mark.integration
class TestDarkModeHtml:
"""Integration tests verifying the rendered HTML contains dark mode elements."""
def test_about_page_contains_color_scheme_attribute(self, client):
"""The <html> element should carry a data-color-scheme-default attribute."""
response = client.get("/about")
assert response.status_code == 200
assert b"data-color-scheme-default=" in response.content
def test_about_page_contains_dark_mode_toggle(self, client):
"""The navbar should contain a dark mode toggle button."""
response = client.get("/about")
assert response.status_code == 200
assert b"darkModeToggle" in response.content
def test_about_page_contains_anti_flash_script(self, client):
"""The page should include the anti-flash colour scheme detection script."""
response = client.get("/about")
assert response.status_code == 200
assert b"colorScheme" in response.content
assert b"prefers-color-scheme" in response.content
def test_about_page_contains_toggle_dark_mode_function(self, client):
"""The page should reference toggleDarkMode via common.js."""
response = client.get("/about")
assert response.status_code == 200
assert b"toggleDarkMode" in response.content