mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-21 15:33:45 +00:00
🧬 test: Pin Built-In Theme Output to the Cache Epoch (#16875)
* test: Pin the Bundled Theme Resolver Output to the Cache Epoch * test: Pin the Resolver Fallbacks of an Empty Theme Definition * test: Pin Only the Themes That Can Enter the Cache * test: Pin an Inline Theme With Role Overrides * test: Pin the Resolver Output by Role Fixtures and Role Fingerprint * test: Pin the Persisted Cache Output Per Role and Mode Scope * test: Generate the Cache Pin Fixtures From the Resolver * test: Refresh the Cache Pin for the Promoted Stylesheet Roles * test: Pin Fixture Inputs Apart From Resolver Output, Sort by Code Point * test: Keep Sample-Independent Output Pinned When Fixture Inputs Move * test: Pin the Accepted Appearance Values With the Resolver Output
This commit is contained in:
parent
945a885394
commit
5d26de6d86
1 changed files with 298 additions and 2 deletions
|
|
@ -1,5 +1,17 @@
|
|||
import { clickHouseTheme } from '@librechat/client';
|
||||
import { themeRoleFingerprint } from 'librechat-data-provider';
|
||||
import {
|
||||
THEME_VERSION,
|
||||
themeRoleFingerprint,
|
||||
themeAppearanceTokens,
|
||||
} from 'librechat-data-provider';
|
||||
import {
|
||||
themeBrandTokens,
|
||||
themeColorTokens,
|
||||
resolveTheme,
|
||||
libreChatTheme,
|
||||
clickHouseTheme,
|
||||
validateThemeDefinition,
|
||||
} from '@librechat/client';
|
||||
import type { ThemeDefinition, ResolvedThemeStyle } from '@librechat/client';
|
||||
import type { ThemeCacheEntry } from '../themeCache';
|
||||
import {
|
||||
themeOwner,
|
||||
|
|
@ -153,3 +165,287 @@ describe('theme cache storage', () => {
|
|||
expect(localStorage.getItem(THEME_CACHE_KEY)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
/**
|
||||
* The baseline the cache's persisted output is pinned to. The cache version keys on the role set
|
||||
* and a hand-bumped `THEME_CACHE_EPOCH`, so a release that changes what a cacheable theme
|
||||
* resolves to without adding a role would replay stale styling at boot. The digest covers what
|
||||
* the cache persists (`buildThemeCache(...).modes`, with the property order canonicalized) for
|
||||
* `librechat` and `clickhouse`, the definitions that can enter the cache (the boot script never
|
||||
* replays one under high contrast), and for generated definitions:
|
||||
* - every color, brand and appearance role overridden alone, theme-wide, in light only and in
|
||||
* dark only (the other mode absent), plus a `none` sample for each shadow-like role;
|
||||
* - every role the resolver derives from others, found by diffing its resolved output against the
|
||||
* bare theme, with all of its sources named together and again with the role named as well, theme-wide and per mode, so
|
||||
* fallback precedence and opting out are covered without listing the chains by hand;
|
||||
* - every brand set theme-wide, in light and in dark with conflicting values;
|
||||
* - definitions with one or both mode blocks absent.
|
||||
* A new role, or a new fallback, joins by construction.
|
||||
*/
|
||||
const PIN = { fingerprint: '1.2.leqd1k', digest: '1fm6x5m' };
|
||||
|
||||
const digestOf = (text: string): string => {
|
||||
let hash = 5381;
|
||||
for (let i = 0; i < text.length; i++) {
|
||||
hash = ((hash * 33) ^ text.charCodeAt(i)) >>> 0;
|
||||
}
|
||||
return hash.toString(36);
|
||||
};
|
||||
|
||||
/** Locale-independent, so the digest does not depend on the collation Jest runs under. */
|
||||
const byCodePoint = (a: string, b: string): number => (a < b ? -1 : Number(a > b));
|
||||
|
||||
const APPEARANCE_CANDIDATES = [
|
||||
'0.5rem',
|
||||
'1.25rem',
|
||||
'soft',
|
||||
'dim',
|
||||
'fill',
|
||||
'600',
|
||||
'0.5',
|
||||
'150ms',
|
||||
'9rem',
|
||||
'0 1px 2px 0 rgb(0 0 0 / 0.2)',
|
||||
'ui-sans-serif, sans-serif',
|
||||
'1.5',
|
||||
'ring',
|
||||
'border',
|
||||
'none',
|
||||
];
|
||||
|
||||
type Scope = 'both' | 'light' | 'dark';
|
||||
type Mode = 'light' | 'dark';
|
||||
type Overrides = {
|
||||
colors?: Record<string, string>;
|
||||
appearance?: Record<string, string>;
|
||||
brands?: Record<string, string>;
|
||||
};
|
||||
type Fixture = { key: string; theme: ThemeDefinition };
|
||||
|
||||
const SCOPES: Scope[] = ['both', 'light', 'dark'];
|
||||
const MODES: Mode[] = ['light', 'dark'];
|
||||
const COLOR_SENTINEL: Record<Mode, (index: number) => string> = {
|
||||
light: (index) => `${10 + index} 20 30`,
|
||||
dark: (index) => `${200 - index} 210 220`,
|
||||
};
|
||||
|
||||
/** A definition whose inactive mode block is absent, not empty. */
|
||||
const define = (
|
||||
name: string,
|
||||
overrides: (mode: Mode) => Overrides,
|
||||
scope: Scope,
|
||||
wideBrands?: Record<string, string>,
|
||||
): ThemeDefinition =>
|
||||
({
|
||||
version: THEME_VERSION,
|
||||
name,
|
||||
...(wideBrands && { brands: wideBrands }),
|
||||
modes: Object.fromEntries(
|
||||
MODES.filter((mode) => scope === 'both' || scope === mode).map((mode) => [
|
||||
mode,
|
||||
overrides(mode),
|
||||
]),
|
||||
),
|
||||
}) as ThemeDefinition;
|
||||
|
||||
const BARE = define('bare', () => ({}), 'both');
|
||||
const isValid = (theme: ThemeDefinition): boolean => validateThemeDefinition(theme).length === 0;
|
||||
|
||||
/** Every candidate the validator accepts for each appearance role, pinned so a narrowing or widening shows. */
|
||||
const ACCEPTED: Record<string, string[]> = Object.fromEntries(
|
||||
themeAppearanceTokens.map((token) => [
|
||||
token,
|
||||
APPEARANCE_CANDIDATES.filter((value) =>
|
||||
isValid(define(token, () => ({ appearance: { [token]: value } }), 'both')),
|
||||
),
|
||||
]),
|
||||
);
|
||||
|
||||
/** The first sample the validator accepts for an appearance role, and `none` when it takes it. */
|
||||
function appearanceSamples(token: string): string[] {
|
||||
const accepted = ACCEPTED[token];
|
||||
if (accepted.length === 0) {
|
||||
throw new Error(`Add a valid sample for the appearance role ${token} to APPEARANCE_CANDIDATES`);
|
||||
}
|
||||
return [...new Set([accepted[0], ...accepted.filter((value) => value === 'none')])];
|
||||
}
|
||||
|
||||
const SAMPLES = Object.fromEntries(
|
||||
themeAppearanceTokens.map((token) => [token, appearanceSamples(token)]),
|
||||
);
|
||||
|
||||
const colorOverrides = (tokens: readonly string[], mode: Mode): Record<string, string> =>
|
||||
Object.fromEntries(tokens.map((token, index) => [token, COLOR_SENTINEL[mode](index)]));
|
||||
|
||||
const appearanceOverrides = (tokens: readonly string[]): Record<string, string> =>
|
||||
Object.fromEntries(tokens.map((token) => [token, SAMPLES[token][0]]));
|
||||
|
||||
/** Role to the roles whose single override changes it, read from the resolver. */
|
||||
function derivedRoles(): { colors: Map<string, string[]>; appearance: Map<string, string[]> } {
|
||||
const base = MODES.map((mode) => resolveTheme(BARE, mode));
|
||||
const found = {
|
||||
colors: new Map<string, Set<string>>(),
|
||||
appearance: new Map<string, Set<string>>(),
|
||||
};
|
||||
const note = (kind: 'colors' | 'appearance', source: string, theme: ThemeDefinition) =>
|
||||
MODES.forEach((mode, index) => {
|
||||
const resolved = resolveTheme(theme, mode);
|
||||
const before = base[index][kind] as Record<string, unknown>;
|
||||
const after = resolved[kind] as Record<string, unknown>;
|
||||
Object.keys(after)
|
||||
.filter((key) => key !== source && after[key] !== before[key])
|
||||
.forEach((key) => found[kind].set(key, (found[kind].get(key) ?? new Set()).add(source)));
|
||||
});
|
||||
themeColorTokens.forEach((token) =>
|
||||
note(
|
||||
'colors',
|
||||
token,
|
||||
define(token, (mode) => ({ colors: colorOverrides([token], mode) }), 'both'),
|
||||
),
|
||||
);
|
||||
themeAppearanceTokens.forEach((token) =>
|
||||
note(
|
||||
'appearance',
|
||||
token,
|
||||
define(token, () => ({ appearance: appearanceOverrides([token]) }), 'both'),
|
||||
),
|
||||
);
|
||||
const sorted = (map: Map<string, Set<string>>) =>
|
||||
new Map([...map].map(([key, sources]) => [key, [...sources].sort()] as [string, string[]]));
|
||||
return { colors: sorted(found.colors), appearance: sorted(found.appearance) };
|
||||
}
|
||||
|
||||
function roleFixtures(): Fixture[] {
|
||||
const colors = themeColorTokens.flatMap((token) =>
|
||||
SCOPES.map((scope) => ({
|
||||
key: `color:${token}:${scope}`,
|
||||
theme: define(token, (mode) => ({ colors: colorOverrides([token], mode) }), scope),
|
||||
})),
|
||||
);
|
||||
const brands = themeBrandTokens.flatMap((token) => [
|
||||
{
|
||||
key: `brand:${token}:wide`,
|
||||
theme: define(token, () => ({}), 'both', { [token]: '#123456' }),
|
||||
},
|
||||
...MODES.map((mode) => ({
|
||||
key: `brand:${token}:${mode}`,
|
||||
theme: define(token, () => ({ brands: { [token]: '#123456' } }), mode),
|
||||
})),
|
||||
{
|
||||
key: `brand:${token}:conflict`,
|
||||
theme: define(
|
||||
token,
|
||||
(mode) => ({ brands: { [token]: mode === 'light' ? '#aa0000' : '#00aa00' } }),
|
||||
'both',
|
||||
{ [token]: '#0000aa' },
|
||||
),
|
||||
},
|
||||
]);
|
||||
const appearance = themeAppearanceTokens.flatMap((token) =>
|
||||
SAMPLES[token].flatMap((value, index) =>
|
||||
SCOPES.map((scope) => ({
|
||||
key: `appearance:${token}:${index}:${scope}`,
|
||||
theme: define(token, () => ({ appearance: { [token]: value } }), scope),
|
||||
})),
|
||||
),
|
||||
);
|
||||
return [...colors, ...brands, ...appearance];
|
||||
}
|
||||
|
||||
/** Each derived role with all of its sources named together, then with the role named as well. */
|
||||
function derivedFixtures(): Fixture[] {
|
||||
const { colors, appearance } = derivedRoles();
|
||||
const fixtures = (
|
||||
kind: 'color' | 'appearance',
|
||||
chains: Map<string, string[]>,
|
||||
overrides: (tokens: string[], mode: Mode) => Overrides,
|
||||
) =>
|
||||
[...chains].flatMap(([target, sources]) =>
|
||||
SCOPES.flatMap((scope) => [
|
||||
{
|
||||
key: `derived:${kind}:${target}:sources:${scope}`,
|
||||
theme: define(target, (mode) => overrides(sources, mode), scope),
|
||||
},
|
||||
{
|
||||
key: `derived:${kind}:${target}:named:${scope}`,
|
||||
theme: define(target, (mode) => overrides([...sources, target], mode), scope),
|
||||
},
|
||||
]),
|
||||
);
|
||||
return [
|
||||
...fixtures('color', colors, (tokens, mode) => ({ colors: colorOverrides(tokens, mode) })),
|
||||
...fixtures('appearance', appearance, (tokens) => ({
|
||||
appearance: appearanceOverrides(tokens),
|
||||
})),
|
||||
];
|
||||
}
|
||||
|
||||
/** Mode blocks that are missing or empty, on a bare theme and on a bundled one. */
|
||||
function modeFixtures(): Fixture[] {
|
||||
const without = (theme: ThemeDefinition, mode: Mode): ThemeDefinition => {
|
||||
const modes = { ...theme.modes };
|
||||
delete modes[mode];
|
||||
return { ...theme, modes };
|
||||
};
|
||||
return [
|
||||
{ key: 'modes:none', theme: { version: THEME_VERSION, name: 'none', modes: {} } },
|
||||
{ key: 'modes:empty', theme: define('empty', () => ({}), 'both') },
|
||||
{ key: 'modes:clickhouse:no-light', theme: without(clickHouseTheme, 'light') },
|
||||
{ key: 'modes:clickhouse:no-dark', theme: without(clickHouseTheme, 'dark') },
|
||||
];
|
||||
}
|
||||
|
||||
/** Property order is positional in the cache entry and means nothing to the page. */
|
||||
const canonical = ({ properties, attributes }: ResolvedThemeStyle) => ({
|
||||
properties: [...properties].sort(([a], [b]) => byCodePoint(a, b)),
|
||||
attributes: Object.fromEntries(Object.entries(attributes).sort(([a], [b]) => byCodePoint(a, b))),
|
||||
});
|
||||
|
||||
const persistedOutput = () => {
|
||||
const fixtures: Fixture[] = [
|
||||
{ key: 'a:librechat', theme: libreChatTheme },
|
||||
{ key: 'a:clickhouse', theme: clickHouseTheme },
|
||||
...roleFixtures(),
|
||||
...derivedFixtures(),
|
||||
...modeFixtures(),
|
||||
].sort((a, b) => byCodePoint(a.key, b.key));
|
||||
return fixtures.map(({ key, theme }) => {
|
||||
const { light, dark } = buildThemeCache(OWNER, key, theme).modes;
|
||||
return [key, canonical(light), canonical(dark)];
|
||||
});
|
||||
};
|
||||
|
||||
/** What the contributor has to do, or an empty string when the pin is current. */
|
||||
function pinStatus(actual: typeof PIN): string {
|
||||
const refreshed = JSON.stringify(actual);
|
||||
if (actual.fingerprint !== PIN.fingerprint) {
|
||||
return `The cache version changed (role set, theme version or epoch), which already retires cached entries: set PIN to ${refreshed}.`;
|
||||
}
|
||||
if (actual.digest !== PIN.digest) {
|
||||
return `The persisted output or the accepted appearance values changed without a version change: bump THEME_CACHE_EPOCH in packages/data-provider/src/theme.ts, then set PIN to the refreshed fingerprint and digest (digest ${actual.digest}).`;
|
||||
}
|
||||
return '';
|
||||
}
|
||||
|
||||
describe('resolver output pin', () => {
|
||||
it('matches the persisted output of every cacheable definition and generated fixture', () => {
|
||||
const status = pinStatus({
|
||||
fingerprint: themeRoleFingerprint(),
|
||||
digest: digestOf(JSON.stringify({ accepted: ACCEPTED, output: persistedOutput() })),
|
||||
});
|
||||
expect(status).toBe('');
|
||||
});
|
||||
|
||||
it('finds the fallback chains in the resolver, not in a list', () => {
|
||||
const { colors, appearance } = derivedRoles();
|
||||
expect(colors.get('rgb-surface-code')).toContain('rgb-surface-primary-alt');
|
||||
expect(colors.get('rgb-link-prose')).toContain('rgb-link');
|
||||
expect(appearance.get('menuShadow')).toContain('shadowLg');
|
||||
});
|
||||
|
||||
it('tells a version change from an output change', () => {
|
||||
expect(pinStatus({ ...PIN, fingerprint: 'other' })).toMatch(/cache version changed/);
|
||||
expect(pinStatus({ ...PIN, digest: 'other' })).toMatch(/bump THEME_CACHE_EPOCH/);
|
||||
expect(pinStatus(PIN)).toBe('');
|
||||
});
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue