feat(theming): settings-store, nav merge util and radius tokens

Phases 0-2 of docs/website/THEMING_AND_NAV.md. Groundwork only: no admin UI,
no consumer wiring, and an instance that never touches the new settings keys
renders exactly as it does today.

Phase 0 - settings store:
- settingsDb.remove() and DELETE /api/v1/admin/settings/:key, the "reset to
  default" primitive. Defaults for these keys live in BRAND_* env, theme.css
  and the hardcoded NAV arrays, so reset has to delete the row rather than
  store a copy of the default. Allowlisted to the five theming/nav keys plus
  hero_layout_draft, admin-only, idempotent.
- GET /api/v1/settings/nav behind requireAuth with no role gate. AdminLayout
  renders for editors and moderators and PlayerPortalLayout for players, and
  none of them can read GET /admin/settings, so without this their nav
  override would silently never apply.
- A fifth router group for it: /public is anonymous, /admin/settings is
  adminOnly, /player is self-scoped data. This is configuration that needs a
  login.
- parseJsonSetting() in utils/settingsJson.js. settings.value is TEXT, so
  every JSON key arrives as a string; malformed or wrong-shaped reads as
  absent, never as an error and never half-applied.
- theme_visual / brand_assets / nav_public join PUBLIC_KEYS; nav_admin and
  nav_player deliberately do not.

Phase 1 - client/src/lib/navOverrides.js, the pure merge util. Presentation
only: it can set label/order/hidden and (grouped navs) group, and nothing
else. It cannot introduce a `to`, cannot touch roles/feature, and hidden:false
cannot un-hide anything - the existing filters run afterward, unchanged, and
remain the boundary.

Phase 2 - promoted 23 border-radius literals in theme.css to four tokens at
today's values (14x8px, 4x999px, 4x10px, 1x12px). The 7px/6px editor chrome
and the two 50% circles stay literal. --shadow-card and --panel-grad were
already tokens.

Tests: 16 new server tests, 20 new client tests. The route-manifest guard now
also asserts /settings/** sits behind requireAuth. Swagger and both route
artifacts regenerated.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2026-08-07 18:15:29 -05:00
parent d765280e28
commit ec0036ce6d
18 changed files with 1042 additions and 28 deletions

View File

@@ -10,8 +10,27 @@ const PUBLIC_KEYS = [
'contact_email',
'site_title',
'hero_layout', // portal hero composition (JSON). Draft key stays admin-only.
'theme_visual', // preset/custom colors, fonts, radii (JSON). See THEMING_AND_NAV.md §6.1.
'brand_assets', // uploaded logo/hero/favicon overrides (JSON). §6.3.
'nav_public', // public site nav overrides (JSON). §6.4.
]
// Admin-configurable theming & navigation (docs/website/THEMING_AND_NAV.md).
// All five are JSON strings and all five are ABSENT by default — no migration
// seeds them. Absence of the row, not an empty value, is what makes a surface
// fall back to BRAND_* env / the hardcoded theme.css / the hardcoded NAV arrays.
//
// nav_admin and nav_player are deliberately not public: an anonymous visitor has
// no use for either, and the admin nav's labels describe the shape of the admin
// surface. They are read by their owners through GET /api/v1/settings/nav (§4.2).
const THEMING_KEYS = ['theme_visual', 'brand_assets', 'nav_public', 'nav_admin', 'nav_player']
// Keys a reset may delete. An explicit allowlist, not "any key": DELETE on an
// arbitrary key would let a bad request drop site_mode or the uo-link config,
// whose absence means something else entirely. hero_layout_draft is included
// because discarding a draft is the same operation.
const DELETABLE_KEYS = [...THEMING_KEYS, 'hero_layout_draft']
// Player self-registration mode. Stored under the 'player_registration' key.
// NOTE: the raw value is never exposed publicly — getPublic() derives boolean
// availability flags from it instead (see below).
@@ -96,6 +115,10 @@ async function set(key, value, updatedBy = null) {
return settingsDb.set(key, value, updatedBy)
}
async function remove(key) {
return settingsDb.remove(key)
}
async function setMany(obj, updatedBy = null) {
for (const [key, value] of Object.entries(obj)) {
await settingsDb.set(key, value, updatedBy)
@@ -155,6 +178,19 @@ async function getPublic() {
return out
}
// The two nav-override keys their own audiences need but cannot read from
// GET /admin/settings (admin-only, while AdminLayout renders for editors and
// moderators and PlayerPortalLayout renders for players — THEMING_AND_NAV.md
// §4.2). Values are returned as stored: raw JSON strings, or null when the
// admin never overrode that nav.
async function getNav() {
const all = await getAll()
return {
nav_admin: all.nav_admin ?? null,
nav_player: all.nav_player ?? null,
}
}
// The client-facing ntfy base URL (no trailing slash), or null when unset.
function publicNtfyUrl() {
const explicit = (process.env.NTFY_PUBLIC_URL || '').trim()
@@ -169,11 +205,15 @@ function publicNtfyUrl() {
module.exports = {
get,
set,
remove,
setMany,
getAll,
getPublic,
getNav,
getInstanceName,
PUBLIC_KEYS,
THEMING_KEYS,
DELETABLE_KEYS,
REGISTRATION_KEY,
REGISTRATION_MODES,
getRegistrationMode,