got-feedBack/feedBack
1
0
Fork 0
mirror of https://github.com/got-feedBack/feedBack.git synced 2026-08-11 03:09:57 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

feat(v3): host theme read surface — window.feedBack.theme + always-present --fbv-* tokens (#646)

Browse Source 
First slice of the host theme contract (#644): give plugins a host-owned way to
read the active theme + its device affordances, so a feature renders correctly
under any theme instead of binding to whichever one the dev saw.

theme-core.js previously only APPLIED themes and emitted --fbv-* vars only while
a theme was equipped (nothing to read in the default state), with no read API.
Now, all additive + feature-detected:

- Always-present default `fb` palette as `--fbv-*` on :root (the un-themed look
  is unchanged — fb-* utilities still use their compiled defaults; this only
  hands plugins a stable host token to read + derive surfaces from). Adds two
  keystone ROLES the palette lacked: `on-accent` (legible fg on the accent fill)
  and `focus-ring`.
- window.feedBack.theme.get() -> {id, isThemed, tokens}; .capabilities() ->
  {glow, gradients, motion} (the device-affordance signal; recolor-only themes
  report defaults, a theme may opt out via `capabilities` in its payload, motion
  is reduced-motion-gated); .prefersReducedMotion().
- Normalized `theme:changed` event from the single apply() chokepoint.

The apply side stays on window.v3Theme; the read surface is attached defensively
so it survives the feedBack bus being (re)built by capabilities.js regardless of
load order. Verified via a headless render (apply/unequip intact, defaults
present + restored, capability opt-out honored, event payload correct) +
tests/js/v3_theme_read_api.test.js. See docs/host-theme-contract.md.


Claude-Session: https://claude.ai/code/session_01QbexxfTt8q2tAn436MqGWF

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
ChrisBeWithYou
2026-07-02 13:57:58 +02:00
committed by GitHub
co-authored by Claude Opus 4.8
parent 7ff9261000
commit d20b33348b
3 changed files with 170 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
static/v3/theme-core.js
+112 -2
View File
@@ -23,7 +23,24 @@
const OPACITY = { 95: '0.95', 90: '0.9', 80: '0.8', 70: '0.7', 60: '0.6',
50: '0.5', 40: '0.4', 30: '0.3', 20: '0.2', 10: '0.1' };
// Default fb palette (mirrors tailwind.config.js `fb`). Emitted as
// always-present `--fbv-*` on :root so `var(--fbv-accent)` resolves even
// un-themed — the un-themed look is unchanged (the fb-* utilities still use
// their compiled defaults; this only hands plugins a stable host token to
// read + derive from). Adds two keystone ROLES the palette lacked:
// `on-accent` (a foreground legible ON the accent fill — the missing piece
// behind white-on-accent contrast bugs) and `focus-ring`.
const DEFAULTS = {
bg: '#0f172a', sidebar: '#111827', card: '#1e293b', cardMuted: '#0b1220',
primary: '#0ea5e9', primaryHi: '#38bdf8', accent: '#ef4444',
text: '#f8fafc', textDim: '#94a3b8', border: '#334155',
good: '#22c55e', mid: '#eab308', low: '#ef4444', gold: '#e8c040',
'on-accent': '#f8fafc', 'focus-ring': '#38bdf8',
};
let _frameStyle = ''; // equipped avatar-frame CSS fragment ('' = none)
let _themeId = null; // equipped theme id (null = default look)
let _themeCaps = null; // equipped theme's declared device capabilities, or null
function hexToRgb(hex) {
const m = /^#?([0-9a-f]{6})$/i.exec(String(hex || '').trim());
@@ -73,12 +90,14 @@
return 'html[data-fb-theme] {\n' + vars + '}\n' + rules;
}
function apply(payload) {
function apply(payload, meta) {
const colors = payload && payload.colors;
let styleEl = document.getElementById(STYLE_ID);
if (!colors) {
if (styleEl) styleEl.remove();
document.documentElement.removeAttribute('data-fb-theme');
_themeId = null; _themeCaps = null;
_emitThemeChanged();
return;
}
if (!styleEl) {
@@ -88,6 +107,13 @@
}
styleEl.textContent = cssFor(colors);
document.documentElement.setAttribute('data-fb-theme', '1');
// Track identity + declared device capabilities for the read API. A
// theme MAY carry `capabilities` (e.g. {glow:false}) in its payload;
// recolor-only themes carry none (→ default affordances reported).
_themeId = (meta && meta.id) || (payload && payload.id) || 'custom';
_themeCaps = (payload && payload.capabilities)
|| (meta && meta.capabilities) || null;
_emitThemeChanged();
}
function setFrame(payload) {
@@ -106,7 +132,7 @@
function applyCosmetics(cosmetics) {
cosmetics = cosmetics || {};
apply((cosmetics.theme || {}).payload || null);
apply((cosmetics.theme || {}).payload || null, cosmetics.theme || null);
setFrame((cosmetics.avatar_frame || {}).payload || null);
}
@@ -123,6 +149,83 @@
} catch (e) { /* offline — keep current look */ }
}
// ── Host theme READ surface (window.feedBack.theme) ──────────────────────
// The apply side stays on window.v3Theme; this is the read/capability side
// plugins consume so a feature can render correctly under any theme instead
// of binding to the one the dev happened to see. See docs/host-theme-contract.md.
// Always-present `--fbv-*` defaults on :root (see DEFAULTS). Additive: the
// un-themed look is unchanged; this only makes var(--fbv-*) resolve so a
// plugin can derive surfaces from host tokens whether or not a theme is on.
function _injectDefaults() {
if (document.getElementById('fb-theme-defaults')) return;
let vars = '';
for (const key in DEFAULTS) {
const rgb = hexToRgb(DEFAULTS[key]);
if (rgb) vars += ' --fbv-' + key + ': ' + rgb + ';\n';
}
const el = document.createElement('style');
el.id = 'fb-theme-defaults';
el.textContent = ':root {\n' + vars + '}\n';
(document.head || document.documentElement).appendChild(el);
}
function prefersReducedMotion() {
try {
return !!(window.matchMedia
&& window.matchMedia('(prefers-reduced-motion: reduce)').matches);
} catch (e) { return false; }
}
// Live snapshot of the resolved role tokens ("r g b" triplets; use as
// rgb(var(--fbv-<key>)) in CSS). Reflects the themed values when a theme is
// equipped, the :root defaults otherwise.
function _readTokens() {
const t = {};
try {
const cs = getComputedStyle(document.documentElement);
for (const key in DEFAULTS) {
const v = cs.getPropertyValue('--fbv-' + key).trim();
if (v) t[key] = v;
}
} catch (e) { /* no computed style available yet */ }
return t;
}
// Whether the ACTIVE theme permits decorative DEVICES — the signal a feature
// reads to pick a device (glow vs. solid) rather than hardcoding one. Today's
// recolor-only themes declare nothing → default affordances; a theme may opt
// out via `capabilities` in its payload (e.g. a clean theme = {glow:false}).
// `motion` is additionally gated by the OS reduced-motion preference.
function capabilities() {
const c = _themeCaps || {};
const allowMotion = c.motion !== undefined ? !!c.motion : true;
return {
glow: c.glow !== undefined ? !!c.glow : true,
gradients: c.gradients !== undefined ? !!c.gradients : true,
motion: allowMotion && !prefersReducedMotion(),
};
}
function get() {
return {
id: _themeId,
isThemed: document.documentElement.hasAttribute('data-fb-theme'),
tokens: _readTokens(),
};
}
function _emitThemeChanged() {
if (window.feedBack && typeof window.feedBack.emit === 'function') {
window.feedBack.emit('theme:changed', {
id: _themeId,
isThemed: document.documentElement.hasAttribute('data-fb-theme'),
tokens: _readTokens(),
capabilities: capabilities(),
});
}
}
window.v3Theme = {
apply, // preview/apply a theme payload directly (null = default)
applyCosmetics, // apply a {theme, avatar_frame} equipped map
@@ -131,6 +234,13 @@
refresh, // re-read equipped cosmetics from /api/profile
};
// Host-owned theme READ surface. Attached defensively so it survives the
// feedBack bus being (re)built by capabilities.js regardless of load order
// (the bus constructor copies pre-existing keys onto itself).
window.feedBack = window.feedBack || {};
window.feedBack.theme = { get, capabilities, prefersReducedMotion };
_injectDefaults();
refresh();
// Re-apply when an equip/unequip happens anywhere (shop screen, capability
// command from a plugin).