RunicGateway/website
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Activity

feat(theming): server-resolved theme engine and admin appearance UI

Browse Source 
Phases 3-4 of docs/website/THEMING_AND_NAV.md. Three presets, the curated font
shortlist, and /admin/appearance to drive them.

The design put the presets in theme.css as [data-theme] blocks. That does not
work: SiteContext writes --accent as an inline style on <html>, which beats any
attribute-selector block, so a preset's accent would have been painted over by
BRAND_ACCENT_COLOR while getPublic().brand.accent -- the value the Android app
themes itself from -- reported the other one.

Presets now live in server/src/config/themePresets.js. themeResolve.js layers
:root <- preset <- custom per field into a token map, getPublic() returns it as
`theme`, and the client writes it onto <html>. One authority for the merge, and
brand.accent is by construction the accent the site paints. theme.css's :root is
untouched, so an instance with no row gets no theme block and renders as today.

Also: presets carry the full 15-token palette (eight would have left Fantasy
with blue-grey borders); the option catalog is served from
GET /settings/theme/options so the form cannot offer what the server rejects;
validation is strict on write and forgiving on read; and the Discord bot now
fetches the effective accent instead of its boot-time env copy.

Fixes a Phase 0 bug in passing: settings/nav.controller.js imported the logger
factory rather than calling it, so a DB fault would have thrown a TypeError
inside the catch instead of returning 500.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
claude
2026-08-07 19:16:23 -05:00
parent 0a2ccafff6
commit 3d6b2e23a7
26 changed files with 2113 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
server/src/router/v1/admin/admin.controller.js
View File

@@ -9,6 +9,8 @@ const announceJobs = require('../../../model/announceJobs/announceJobs.model')
const newsGump = require('../../../utils/newsGump')
const pushDispatch = require('../../../utils/pushDispatch')
const { cleanBody } = require('../../../utils/sanitizeHtml')
const { parseJsonSetting } = require('../../../utils/settingsJson')
const { validateThemeVisual } = require('../../../utils/themeResolve')
const log = require('../../../utils/logger')('admin')
@@ -529,6 +531,22 @@ async function updateSettings(req, res) {
if (typeof updates.homepage_teaser === 'string') {
updates.homepage_teaser = cleanBody(updates.homepage_teaser)
}
// theme_visual is JSON whose values become CSS custom properties, so every
// one has to come from the closed sets in config/themePresets.js. The read
// path drops anything invalid anyway (THEMING_AND_NAV.md §4.4), but silently
// storing a value that will never apply is a bad admin experience — reject it
// with the offending field named instead. Accepts an object or the stringified
// form, and stores it stringified either way, since settings.value is TEXT.
if ('theme_visual' in updates) {
const raw = updates.theme_visual
const parsed = typeof raw === 'string' ? parseJsonSetting(raw) : raw
if (typeof raw === 'string' && parsed === null) {
return res.status(400).json({ message: 'theme_visual must be a JSON object' })
}
const check = validateThemeVisual(parsed)
if (!check.ok) return res.status(400).json({ message: check.message })
updates.theme_visual = JSON.stringify(parsed)
}
try {
await settings.setMany(updates, req.user.id)
await activity.log({ req, action: 'settings.update', detail: { keys: Object.keys(updates) } })

2
server/src/router/v1/settings/index.js
View File

@@ -23,11 +23,13 @@ const { requireAuth } = require('../../../auth/session.middleware')
const noindex = require('../../../middleware/noindex')
const navRouter = require('./nav.router')
const themeRouter = require('./theme.router')
const settingsRouter = express.Router()
settingsRouter.use(noindex, requireAuth)
settingsRouter.use('/nav', navRouter)
settingsRouter.use('/theme', themeRouter)
module.exports = settingsRouter

7
server/src/router/v1/settings/nav.controller.js
View File

@@ -1,5 +1,10 @@
const settings = require('../../../model/settings/settings.model')
const log = require('../../../utils/logger')
// The logger module exports a FACTORY — calling it is what yields {error, warn,
// info, debug}. Using the factory directly makes `log.error` undefined, which
// would turn a DB fault into a TypeError thrown inside the catch (no response
// sent, request left hanging) instead of a 500.
const log = require('../../../utils/logger')('settings')
// The nav overrides for the two authenticated layouts. Values are the raw stored
// JSON strings (settings.value is TEXT) or null; the caller parses them with the

17
server/src/router/v1/settings/theme.controller.js Normal file
View File

@@ -0,0 +1,17 @@
const { themeOptions } = require('../../../utils/themeResolve')
// The theme catalog the admin appearance form builds its controls from: the
// presets and their swatches, the curated font shortlist, the shadow depths,
// and which color and radius fields are editable.
//
// Served rather than duplicated in client code so the options the form OFFERS
// can never drift from the ones validateThemeVisual() ACCEPTS — a drift shows
// up as an admin picking a font and the save 400ing for no visible reason.
//
// Static: derived from config/themePresets.js with no DB read, so there is
// nothing here to fail and no error branch to write.
function getThemeOptions(req, res) {
return res.json(themeOptions())
}
module.exports = { getThemeOptions }

26
server/src/router/v1/settings/theme.router.js Normal file
View File

@@ -0,0 +1,26 @@
// Settings · Theme — the closed sets the admin appearance form is built from.
//
// Mounted at /api/v1/settings/theme by settings/index.js, which already applied
// `noindex, requireAuth`. No role gate is added here for the same reason the
// group has none: it is a static catalog of presets and font names, not
// configuration and not anything about the caller. The route that WRITES a
// theme is PUT /api/v1/admin/settings, which is admin-only.
const express = require('express')
const ctrl = require('./theme.controller')
const themeRouter = express.Router()
themeRouter.get(
'/options',
// #swagger.tags = ['Settings']
// #swagger.summary = 'Theme presets and the curated option lists'
// #swagger.description = 'The closed sets an admin may choose from when theming the site: the three presets (with swatch colors), the curated Google Fonts shortlist per role, the shadow depths, and the editable color/radius field names. Served so the admin form can never offer a value the server would reject. Static — no database read.'
// #swagger.security = [{ "cookieAuth": [] }, { "bearerAuth": [] }]
/* #swagger.responses[200] = { description: 'Theme option catalog', content: { "application/json": { schema: { $ref: "#/components/schemas/ThemeOptions" } } } } */
/* #swagger.responses[401] = { description: 'Not authenticated', content: { "application/json": { schema: { $ref: "#/components/schemas/Error" } } } } */
ctrl.getThemeOptions,
)
module.exports = themeRouter