The site-independent theme engine moves from wayBetter for X into the framework: - runtime/themeSpec.ts: theme document types, the schema's defaults (BASE_*), sanitizing, import, overrides, ensureContrast, font roles/stacks, font choices, backgrounds. - runtime/themeChoice.ts: ThemeChoice and createThemeCatalog(builtins) (normalize, base, resolve, palette, all), choiceForId, serializeChoice. - runtime/themeRuntime.ts: installThemeRuntime(win, site) (live CSS over the site's rules, --wb-* vars, site color mode, first-frame snapshot), collectRules, resolvedFonts. - runtime/fonts.ts: bundled fonts and owner-downloaded Google Fonts from bytes. - themeApi exports hexToRgb, mix and MONO_FAMILIES (one copy: themeTokens and themeSpec use them). - host theme.rs: ThemeChoice/ThemeScopes over a site's ThemeSite (envelope checks against theme.schema.json, which theme a tab shows, page color, delivery script).
521 lines
31 KiB
TypeScript
521 lines
31 KiB
TypeScript
// Theme documents: a wayBetter theme is a JSON document (like a BetterDiscord theme, but data instead
|
|
// of a stylesheet) describing colors, type, shape, density, layout, background and motion; the format
|
|
// is `theme.schema.json` in the `waybetter` package. This module is the document side of the theme
|
|
// engine: types, the schema's defaults, sanitizing, import, panel overrides, legibility, font roles
|
|
// and stacks, and page backgrounds. Pure, so it runs in the page runtime, the settings previews and
|
|
// the tests. What a theme does to one site's page (its selectors, its palette) is the site's
|
|
// (themeRuntime.ts takes a site adapter).
|
|
//
|
|
// Safety: a theme is sanitized field by field before it becomes CSS. Colors are six-digit hex,
|
|
// numbers are clamped, enums are fixed, font names match a strict pattern, background images are
|
|
// `data:image/*;base64` only, and CSS is built from those values (never concatenated from raw
|
|
// strings). The single escape hatch is `css`, which is the same trust level as the owner's own
|
|
// Custom CSS and is shown as such when a theme is imported.
|
|
//
|
|
// Fonts: sites usually block remote and `data:` fonts (CSP `font-src`), so a theme may name installed
|
|
// system fonts, "Geist" / "Geist Mono" (bundled and registered from bytes: `FontFace(ArrayBuffer)` is
|
|
// not a fetch), or Google Fonts families the owner downloaded (`source: "google"`, fonts.ts).
|
|
|
|
import { FONT_ROLE_NAMES, MONO_FAMILIES, contrastRatio, hexToRgb, mix, relativeLuminance, type FontRoleName } from './themeApi.ts';
|
|
import { deriveColors } from './themeTokens.ts';
|
|
|
|
export { FONT_ROLE_NAMES } from './themeApi.ts';
|
|
export type { FontRoleName } from './themeApi.ts';
|
|
|
|
export type Role = 'bg' | 'surface' | 'elevated' | 'border' | 'text' | 'muted' | 'accent';
|
|
/** The site's filled primary button (X: "Post"/"Follow"): an `inverse` background with an `onInverse` label. */
|
|
export type ButtonRole = 'inverse' | 'onInverse';
|
|
export type Palette = Record<Role, string> & Partial<Record<ButtonRole, string>>;
|
|
/** `page` is the canvas behind the site's columns (defaults to `bg`); the columns stay on `bg`. */
|
|
export type ThemeColors = Palette & { page?: string };
|
|
|
|
export type Density = 'compact' | 'default' | 'comfortable';
|
|
export type AvatarShape = 'circle' | 'rounded' | 'square';
|
|
export type Pattern = 'dots' | 'grid' | 'diagonal' | 'scanlines' | 'paper' | 'clouds';
|
|
export type Background =
|
|
| { kind: 'none' }
|
|
| { kind: 'gradient'; from: string; to: string; angle: number; glow?: string }
|
|
| { kind: 'pattern'; pattern: Pattern; ink: string; opacity: number; size: number }
|
|
| { kind: 'image'; url: string; fit: 'cover' | 'tile'; dim: number };
|
|
|
|
/**
|
|
* One role's font (roles: themeApi.ts `FONT_ROLE_NAMES`). `family` is a font stack; empty keeps the
|
|
* inherited family and only changes the rest. `source: "google"` says the first family comes from
|
|
* Google Fonts (downloaded once, asked first when a theme is imported, loaded from bytes). `weight`
|
|
* (100-900), `size` (0.75-1.5, relative to the site's size), `tracking` (em) and `tabular` figures
|
|
* are optional; the interface role takes only `family`/`source` (its size, weights and tracking are
|
|
* `scale`, `weight`, `bold` and `tracking` of the whole theme).
|
|
*/
|
|
export type FontRoleSpec = { family: string[]; source?: 'google'; weight?: number; size?: number; tracking?: number; tabular?: boolean };
|
|
export type FontRole = 'inherit' | FontRoleSpec;
|
|
export type FontRoles = Record<FontRoleName, FontRole>;
|
|
|
|
export type FontSpec = {
|
|
/**
|
|
* Interface font stack (replaces the site's own font everywhere). Empty keeps the site's.
|
|
* Shorthand kept for older theme files and older apps: it always equals `roles.interface`'s family.
|
|
*/
|
|
family: string[];
|
|
/** Post text stack (e.g. a serif reading face); shorthand of `roles.post`'s family. */
|
|
tweet: string[];
|
|
/** Which font goes where. Every role inherits from `interface` unless it says otherwise. */
|
|
roles: FontRoles;
|
|
/** Multiplies the site's pixel font sizes (0.85-1.2). */
|
|
scale: number;
|
|
/** Regular weight (300-500) and bold weight (500-800) that replace the site's 400/700. */
|
|
weight: number;
|
|
bold: number;
|
|
/** Letter spacing in em (-0.03-0.06). */
|
|
tracking: number;
|
|
/** Line height multiplier for post text (0 keeps the site's). */
|
|
leading: number;
|
|
};
|
|
export type ShapeSpec = { radius: number; button: number; avatar: AvatarShape };
|
|
export type LayoutSpec = { column: number; sidebar: number; density: Density; cards: boolean; frame: boolean };
|
|
export type EffectsSpec = { motion: number; hover: 'none' | 'tint' | 'lift' | 'glow'; shadow: 'none' | 'soft' | 'deep'; crt: boolean };
|
|
|
|
export type ThemeSpec = {
|
|
id: string;
|
|
name: string;
|
|
description: string;
|
|
author: string;
|
|
version: 1;
|
|
/** Which way the theme leans; used for scrollbars/form controls and previews. */
|
|
mode: 'light' | 'dark' | 'auto';
|
|
/** null keeps the site's own colors (X: Default / Dim / Lights out). */
|
|
colors: ThemeColors | null;
|
|
font: FontSpec;
|
|
shape: ShapeSpec;
|
|
layout: LayoutSpec;
|
|
background: Background;
|
|
effects: EffectsSpec;
|
|
/** Free-form CSS appended last (owner-trusted, like Custom CSS). */
|
|
css: string;
|
|
};
|
|
|
|
/** Panel overrides: any group may be partially overridden on top of the selected theme. */
|
|
export type ThemeOverrides = {
|
|
colors?: Partial<ThemeColors>;
|
|
/** `roles` is merged role by role (a named role replaces that role only). */
|
|
font?: Partial<Omit<FontSpec, 'roles'>> & { roles?: Partial<FontRoles> };
|
|
shape?: Partial<ShapeSpec>;
|
|
layout?: Partial<LayoutSpec>;
|
|
background?: Background;
|
|
effects?: Partial<EffectsSpec>;
|
|
/** The theme's own CSS as edited in the panel (replaces the theme document's `css`). */
|
|
css?: { text: string };
|
|
};
|
|
|
|
// ---------------------------------------------------------------------------------------------
|
|
// The schema's defaults: a theme that sets nothing changes nothing (the site keeps its own geometry;
|
|
// a site's structure CSS only emits rules where a theme differs from these).
|
|
|
|
export const BASE_SHAPE: ShapeSpec = { radius: 16, button: 9999, avatar: 'circle' };
|
|
export const INHERIT_ROLES: FontRoles = { interface: 'inherit', post: 'inherit', heading: 'inherit', numbers: 'inherit', mono: 'inherit', chrome: 'inherit', dialog: 'inherit' };
|
|
/** A font spec from the interface/post stacks alone (every other role inherits). */
|
|
export const withRoles = (font: Omit<FontSpec, 'roles'>): FontSpec => ({
|
|
...font,
|
|
roles: { ...INHERIT_ROLES, ...(font.family.length ? { interface: { family: font.family } } : {}), ...(font.tweet.length ? { post: { family: font.tweet } } : {}) },
|
|
});
|
|
export const BASE_FONT: FontSpec = withRoles({ family: [], tweet: [], scale: 1, weight: 400, bold: 700, tracking: 0, leading: 0 });
|
|
export const BASE_LAYOUT: LayoutSpec = { column: 600, sidebar: 350, density: 'default', cards: false, frame: false };
|
|
export const BASE_EFFECTS: EffectsSpec = { motion: 0, hover: 'none', shadow: 'none', crt: false };
|
|
|
|
/** The system UI stack themes put after their own sans-serif families. */
|
|
export const SYSTEM_SANS = ['Segoe UI', '-apple-system', 'BlinkMacSystemFont', 'system-ui', 'sans-serif'];
|
|
|
|
// ---------------------------------------------------------------------------------------------
|
|
// Colors and contrast (luminance and ratios: themeApi.ts)
|
|
|
|
export const isHex = (value: unknown): value is string => typeof value === 'string' && /^#[0-9a-f]{6}$/i.test(value);
|
|
/** `#rrggbb` + alpha as `rgba()`. */
|
|
export const rgba = (hex: string, alpha: number) => `rgba(${hexToRgb(hex).join(', ')}, ${+alpha.toFixed(3)})`;
|
|
|
|
/** Moves `color` toward black or white until it reaches `ratio` against every surface. */
|
|
function reach(color: string, surfaces: string[], ratio: number): string {
|
|
const worst = (c: string) => Math.min(...surfaces.map(s => contrastRatio(c, s)));
|
|
if (worst(color) >= ratio) return color;
|
|
const lightSurfaces = surfaces.reduce((sum, s) => sum + relativeLuminance(s), 0) / surfaces.length > 0.18;
|
|
const pole = lightSurfaces ? '#000000' : '#ffffff';
|
|
for (let t = 0.04; t <= 1; t += 0.04) {
|
|
const next = mix(color, pole, t);
|
|
if (worst(next) >= ratio) return next;
|
|
}
|
|
return pole;
|
|
}
|
|
|
|
/**
|
|
* Guarantees legibility for any palette (built-in, imported or overridden): text, secondary text
|
|
* and links reach WCAG AA (4.5:1) on every surface, including the page canvas, and the site's filled
|
|
* button keeps a readable label and stands out from the page (3:1).
|
|
*/
|
|
export function ensureContrast<T extends Palette & { page?: string }>(colors: T): T {
|
|
const surfaces = [colors.bg, colors.surface, colors.elevated, ...(colors.page ? [colors.page] : [])];
|
|
const out = { ...colors };
|
|
out.text = reach(colors.text, surfaces, 7);
|
|
out.muted = reach(colors.muted, surfaces, 4.5);
|
|
// Links live inside the columns, never on the page canvas.
|
|
out.accent = reach(colors.accent, [colors.bg, colors.surface, colors.elevated], 4.5);
|
|
const inverse = colors.inverse ?? out.text;
|
|
const onInverse = colors.onInverse ?? colors.bg;
|
|
out.inverse = reach(inverse, [colors.bg], 3);
|
|
out.onInverse = reach(onInverse, [out.inverse], 4.5);
|
|
return out;
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------
|
|
// Sanitizing
|
|
|
|
const GENERIC_FONTS = new Set(['system-ui', 'sans-serif', 'serif', 'monospace', 'cursive', 'ui-sans-serif', 'ui-serif', 'ui-monospace', 'ui-rounded', '-apple-system', 'BlinkMacSystemFont']);
|
|
const FONT_NAME = /^[A-Za-z0-9][A-Za-z0-9 .\-]{0,47}$/;
|
|
const DATA_IMAGE = /^data:image\/(png|jpeg|webp|gif|avif);base64,[A-Za-z0-9+/]+={0,2}$/;
|
|
export const MAX_IMAGE_CHARS = 1_100_000;
|
|
export const MAX_CSS_CHARS = 60_000;
|
|
const PATTERNS: Pattern[] = ['dots', 'grid', 'diagonal', 'scanlines', 'paper', 'clouds'];
|
|
|
|
const obj = (value: unknown): Record<string, unknown> => value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
|
|
const num = (value: unknown, min: number, max: number, fallback: number) => typeof value === 'number' && Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
|
|
const pick = <T extends string>(value: unknown, options: readonly T[], fallback: T): T => options.includes(value as T) ? value as T : fallback;
|
|
const text = (value: unknown, max: number, fallback = '') => typeof value === 'string' ? value.replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, max) : fallback;
|
|
|
|
export function sanitizeFonts(value: unknown): string[] {
|
|
if (!Array.isArray(value)) return [];
|
|
return value.filter((name): name is string => typeof name === 'string' && (GENERIC_FONTS.has(name) || FONT_NAME.test(name))).slice(0, 8);
|
|
}
|
|
|
|
/** A theme needs its background, text and accent; any other role it leaves out is derived from the
|
|
* base structure (themeTokens.ts `deriveColors`), so every theme has the same proportions. */
|
|
function sanitizeColors(value: unknown): ThemeColors | null {
|
|
const source = obj(value);
|
|
if (!(['bg', 'text', 'accent'] as const).every(role => isHex(source[role]))) return null;
|
|
const named = Object.fromEntries((['bg', 'surface', 'elevated', 'border', 'text', 'muted', 'accent'] as Role[])
|
|
.filter(role => isHex(source[role])).map(role => [role, (source[role] as string).toLowerCase()]));
|
|
const colors = deriveColors(named as { bg: string; text: string; accent: string }) as ThemeColors;
|
|
for (const role of ['inverse', 'onInverse', 'page'] as const) if (isHex(source[role])) colors[role] = (source[role] as string).toLowerCase();
|
|
return colors;
|
|
}
|
|
|
|
export function sanitizeBackground(value: unknown): Background {
|
|
const source = obj(value);
|
|
if (source.kind === 'gradient' && isHex(source.from) && isHex(source.to)) {
|
|
return { kind: 'gradient', from: source.from.toLowerCase(), to: source.to.toLowerCase(), angle: Math.round(num(source.angle, 0, 360, 180)), ...(isHex(source.glow) ? { glow: source.glow.toLowerCase() } : {}) };
|
|
}
|
|
if (source.kind === 'pattern' && isHex(source.ink)) {
|
|
return { kind: 'pattern', pattern: pick(source.pattern, PATTERNS, 'dots'), ink: source.ink.toLowerCase(), opacity: num(source.opacity, 0, 0.6, 0.1), size: Math.round(num(source.size, 2, 400, 24)) };
|
|
}
|
|
if (source.kind === 'image' && typeof source.url === 'string' && source.url.length <= MAX_IMAGE_CHARS && DATA_IMAGE.test(source.url)) {
|
|
return { kind: 'image', url: source.url, fit: pick(source.fit, ['cover', 'tile'] as const, 'cover'), dim: num(source.dim, 0.35, 0.95, 0.6) };
|
|
}
|
|
return { kind: 'none' };
|
|
}
|
|
|
|
/** Bounds of a role's own settings (the JSON Schema says the same; tested). */
|
|
export const ROLE_LIMITS = { weight: [100, 900], size: [0.75, 1.5], tracking: [-0.05, 0.1] } as const;
|
|
|
|
/** One role from JSON: "inherit", or a stack with optional extras (clamped; unknown keys dropped). */
|
|
export function sanitizeFontRole(value: unknown, role: FontRoleName): FontRole {
|
|
if (value === 'inherit' || value === null || value === undefined) return 'inherit';
|
|
const source = obj(value);
|
|
if (!Object.keys(source).length) return 'inherit';
|
|
const family = sanitizeFonts(source.family);
|
|
const out: FontRoleSpec = { family };
|
|
if (source.source === 'google' && family.length && !GENERIC_FONTS.has(family[0]!)) out.source = 'google';
|
|
if (role !== 'interface') {
|
|
if (typeof source.weight === 'number' && Number.isFinite(source.weight)) out.weight = Math.round(num(source.weight, ...ROLE_LIMITS.weight, 400));
|
|
if (typeof source.size === 'number' && Number.isFinite(source.size)) out.size = +num(source.size, ...ROLE_LIMITS.size, 1).toFixed(3);
|
|
if (typeof source.tracking === 'number' && Number.isFinite(source.tracking)) out.tracking = +num(source.tracking, ...ROLE_LIMITS.tracking, 0).toFixed(4);
|
|
if (source.tabular === true) out.tabular = true;
|
|
}
|
|
// A role that changes nothing is the same as inheriting.
|
|
return Object.keys(out).length === 1 && !family.length ? 'inherit' : out;
|
|
}
|
|
|
|
const roleFamily = (role: FontRole): string[] => role === 'inherit' ? [] : role.family;
|
|
/** A role with a new family, keeping its other settings (and its Google source only for the same font). */
|
|
export function withFamily(role: FontRole, family: string[], source?: 'google'): FontRole {
|
|
const rest = role === 'inherit' ? {} : { ...role };
|
|
delete (rest as Partial<FontRoleSpec>).source;
|
|
delete (rest as Partial<FontRoleSpec>).family;
|
|
const next: FontRoleSpec = { ...rest, family, ...(source && family.length ? { source } : {}) };
|
|
return Object.keys(next).length === 1 && !family.length ? 'inherit' : next;
|
|
}
|
|
|
|
/**
|
|
* The roles of a font group from JSON over `base`: `roles.<name>` wins; the legacy shorthand
|
|
* (`family` → interface, `tweet` → post) applies when that role is not named, so theme files and
|
|
* saved customizations from before font roles keep working.
|
|
*/
|
|
function sanitizeRoles(source: Record<string, unknown>, base: FontSpec): FontRoles {
|
|
const named = obj(source.roles);
|
|
const roles = { ...base.roles };
|
|
for (const role of FONT_ROLE_NAMES) if (role in named) roles[role] = sanitizeFontRole(named[role], role);
|
|
if (!('interface' in named) && 'family' in source) roles.interface = withFamily(base.roles.interface, sanitizeFonts(source.family), sameFirst(source.family, base.roles.interface));
|
|
if (!('post' in named) && 'tweet' in source) roles.post = withFamily(base.roles.post, sanitizeFonts(source.tweet), sameFirst(source.tweet, base.roles.post));
|
|
return roles;
|
|
}
|
|
/** Keeps a role's Google source when the shorthand still names the same first family. */
|
|
function sameFirst(stack: unknown, role: FontRole): 'google' | undefined {
|
|
return role !== 'inherit' && role.source === 'google' && Array.isArray(stack) && stack[0] === role.family[0] ? 'google' : undefined;
|
|
}
|
|
|
|
function sanitizeFont(value: unknown, base: FontSpec): FontSpec {
|
|
const source = obj(value);
|
|
const roles = sanitizeRoles(source, base);
|
|
return {
|
|
family: roleFamily(roles.interface),
|
|
tweet: roleFamily(roles.post),
|
|
roles,
|
|
scale: num(source.scale, 0.85, 1.2, base.scale),
|
|
weight: Math.round(num(source.weight, 300, 500, base.weight)),
|
|
bold: Math.round(num(source.bold, 500, 800, base.bold)),
|
|
tracking: num(source.tracking, -0.03, 0.06, base.tracking),
|
|
leading: source.leading === 0 ? 0 : num(source.leading, 1.2, 1.8, base.leading),
|
|
};
|
|
}
|
|
const sanitizeShape = (value: unknown, base: ShapeSpec): ShapeSpec => {
|
|
const source = obj(value);
|
|
return { radius: Math.round(num(source.radius, 0, 28, base.radius)), button: Math.round(num(source.button, 0, 9999, base.button)), avatar: pick(source.avatar, ['circle', 'rounded', 'square'] as const, base.avatar) };
|
|
};
|
|
const sanitizeLayout = (value: unknown, base: LayoutSpec): LayoutSpec => {
|
|
const source = obj(value);
|
|
return {
|
|
column: Math.round(num(source.column, 520, 820, base.column)), sidebar: Math.round(num(source.sidebar, 290, 400, base.sidebar)),
|
|
density: pick(source.density, ['compact', 'default', 'comfortable'] as const, base.density),
|
|
cards: typeof source.cards === 'boolean' ? source.cards : base.cards, frame: typeof source.frame === 'boolean' ? source.frame : base.frame,
|
|
};
|
|
};
|
|
const sanitizeEffects = (value: unknown, base: EffectsSpec): EffectsSpec => {
|
|
const source = obj(value);
|
|
return {
|
|
motion: Math.round(num(source.motion, 0, 400, base.motion)), hover: pick(source.hover, ['none', 'tint', 'lift', 'glow'] as const, base.hover),
|
|
shadow: pick(source.shadow, ['none', 'soft', 'deep'] as const, base.shadow), crt: typeof source.crt === 'boolean' ? source.crt : base.crt,
|
|
};
|
|
};
|
|
|
|
export const slug = (value: string) => value.toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || 'theme';
|
|
|
|
/** Any JSON to a complete, safe theme. Missing groups fall back to the schema's defaults. */
|
|
export function sanitizeSpec(input: unknown): ThemeSpec {
|
|
const source = obj(input);
|
|
const name = text(source.name, 60) || 'Untitled theme';
|
|
const id = typeof source.id === 'string' && /^[a-z0-9-]{1,40}$/.test(source.id) ? source.id : slug(name);
|
|
return {
|
|
id, name, description: text(source.description, 200), author: text(source.author, 60), version: 1,
|
|
mode: pick(source.mode, ['light', 'dark', 'auto'] as const, 'auto'),
|
|
colors: sanitizeColors(source.colors),
|
|
font: sanitizeFont(source.font, BASE_FONT),
|
|
shape: sanitizeShape(source.shape, BASE_SHAPE),
|
|
layout: sanitizeLayout(source.layout, BASE_LAYOUT),
|
|
background: sanitizeBackground(source.background),
|
|
effects: sanitizeEffects(source.effects, BASE_EFFECTS),
|
|
css: typeof source.css === 'string' ? source.css.slice(0, MAX_CSS_CHARS) : '',
|
|
};
|
|
}
|
|
|
|
/** Parses an imported file; errors are human-readable. */
|
|
export function parseThemeJson(json: string): { theme: ThemeSpec; warnings: string[] } | { error: string } {
|
|
let raw: unknown;
|
|
try { raw = JSON.parse(json); } catch { return { error: 'This file is not valid JSON.' }; }
|
|
const source = obj(raw);
|
|
if (typeof source.name !== 'string' || !source.name.trim()) return { error: 'A theme needs a "name".' };
|
|
const theme = sanitizeSpec(raw);
|
|
const warnings: string[] = [];
|
|
if (source.colors !== undefined && source.colors !== null && !theme.colors) warnings.push('Colors were ignored: bg, text and accent must be #rrggbb (the other roles are derived when missing).');
|
|
if (theme.css) warnings.push('Contains custom CSS, which runs inside the site like your own Custom CSS.');
|
|
if (source.background && theme.background.kind === 'none' && obj(source.background).kind !== 'none') warnings.push('The background was ignored (images must be data:image/png, jpeg, webp, gif or avif, up to about 800 KB).');
|
|
if (theme.colors) {
|
|
const fixed = ensureContrast(theme.colors);
|
|
if (fixed.text !== theme.colors.text || fixed.muted !== theme.colors.muted || fixed.accent !== theme.colors.accent) warnings.push('Some text colors were adjusted to stay readable.');
|
|
}
|
|
return { theme, warnings };
|
|
}
|
|
|
|
/** Applies panel overrides (and an accent) on top of a theme. Colors are then made legible. */
|
|
export function applyOverrides(theme: ThemeSpec, overrides: ThemeOverrides = {}, accent: string | null = null): ThemeSpec {
|
|
const o = obj(overrides) as ThemeOverrides;
|
|
let colors = theme.colors ? { ...theme.colors, ...Object.fromEntries(Object.entries(obj(o.colors)).filter(([, v]) => isHex(v))) } as ThemeColors : null;
|
|
if (colors && accent) colors = { ...colors, accent, ...(theme.colors?.inverse === theme.colors?.accent ? { inverse: accent } : {}) };
|
|
return {
|
|
...theme,
|
|
colors: colors ? ensureContrast(colors) : null,
|
|
// Missing keys fall back to the theme's own; the legacy `family`/`tweet` shorthand still overrides.
|
|
font: o.font ? sanitizeFont(o.font, theme.font) : theme.font,
|
|
shape: o.shape ? sanitizeShape({ ...theme.shape, ...o.shape }, theme.shape) : theme.shape,
|
|
layout: o.layout ? sanitizeLayout({ ...theme.layout, ...o.layout }, theme.layout) : theme.layout,
|
|
background: o.background ? sanitizeBackground(o.background) : theme.background,
|
|
effects: o.effects ? sanitizeEffects({ ...theme.effects, ...o.effects }, theme.effects) : theme.effects,
|
|
css: o.css && typeof o.css.text === 'string' ? o.css.text.slice(0, MAX_CSS_CHARS) : theme.css,
|
|
};
|
|
}
|
|
|
|
/** True when a theme changes nothing about the site (the site's own look without overrides). */
|
|
export function isNeutral(theme: ThemeSpec): boolean {
|
|
return !theme.colors && JSON.stringify([theme.font, theme.shape, theme.layout, theme.effects]) === JSON.stringify([BASE_FONT, BASE_SHAPE, BASE_LAYOUT, BASE_EFFECTS])
|
|
&& theme.background.kind === 'none' && !theme.css;
|
|
}
|
|
|
|
// ---------------------------------------------------------------------------------------------
|
|
// Fonts
|
|
|
|
/** Bundled families and the names they are registered under (shell: @fontsource; site pages: FontFace, fonts.ts). */
|
|
export const BUNDLED_FONTS: Record<string, string> = { 'Geist': 'Geist Variable', 'Geist Mono': 'Geist Mono Variable' };
|
|
|
|
export function fontStack(names: string[]): string {
|
|
const out: string[] = [];
|
|
for (const name of names) {
|
|
const real = BUNDLED_FONTS[name];
|
|
if (real) out.push(`"${real}"`);
|
|
out.push(GENERIC_FONTS.has(name) ? name : `"${name}"`);
|
|
}
|
|
// Emoji and CJK keep working whatever the theme names.
|
|
return [...new Set(out), '"Segoe UI Emoji"', '"Apple Color Emoji"', 'sans-serif'].join(', ');
|
|
}
|
|
/** Roles that are drawn inside the site's page (chrome is wayBetter's own window). */
|
|
export const PAGE_ROLES: FontRoleName[] = ['interface', 'post', 'heading', 'numbers', 'mono', 'dialog'];
|
|
const rolesUsing = (theme: ThemeSpec, roles: readonly FontRoleName[]) => roles.flatMap(role => roleFamily(theme.font.roles[role]));
|
|
/** Bundled families (Geist, Geist Mono) a theme names in the site's page. */
|
|
export const bundledFontsUsed = (theme: ThemeSpec, roles: readonly FontRoleName[] = PAGE_ROLES) => {
|
|
const names = new Set(rolesUsing(theme, roles));
|
|
return Object.keys(BUNDLED_FONTS).filter(name => names.has(name));
|
|
};
|
|
/** Google Fonts families a theme uses (`source: "google"`), for the given roles. */
|
|
export function googleFontsUsed(theme: ThemeSpec, roles: readonly FontRoleName[] = FONT_ROLE_NAMES): string[] {
|
|
const out = new Set<string>();
|
|
for (const role of roles) {
|
|
const spec = theme.font.roles[role];
|
|
if (spec !== 'inherit' && spec.source === 'google' && spec.family[0]) out.add(spec.family[0]);
|
|
}
|
|
return [...out];
|
|
}
|
|
|
|
/** A role resolved to what is drawn: the stack actually used and its settings. */
|
|
export type ResolvedFontRole = {
|
|
/** CSS `font-family`. */
|
|
stack: string;
|
|
/** The families of that stack (empty when it is the site's or app's own font). */
|
|
family: string[];
|
|
/** True when the family comes from another role (or the site/app default). */
|
|
inherited: boolean;
|
|
/** A Google Fonts family the stack starts with. */
|
|
google: string | null;
|
|
weight: number | null;
|
|
size: number;
|
|
tracking: number | null;
|
|
tabular: boolean;
|
|
};
|
|
export type ResolvedFontRoles = Record<FontRoleName, ResolvedFontRole>;
|
|
|
|
/**
|
|
* Every role resolved. `site` is the stack an inheriting interface uses: the site's own font in its
|
|
* page, wayBetter's own UI font in the shell. Every other role inherits the interface, except that an
|
|
* inheriting `mono` keeps a monospaced stack (`mono`: themeApi.ts `MONO_FAMILIES`, code rarely suits
|
|
* an interface font).
|
|
*/
|
|
export function resolveFontRoles(font: FontSpec, site: string, mono = fontStack(MONO_FAMILIES)): ResolvedFontRoles {
|
|
const base = font.roles.interface;
|
|
const baseFamily = roleFamily(base);
|
|
const root: ResolvedFontRole = {
|
|
stack: baseFamily.length ? fontStack(baseFamily) : site, family: baseFamily, inherited: !baseFamily.length,
|
|
google: base !== 'inherit' && base.source === 'google' ? baseFamily[0] ?? null : null,
|
|
weight: null, size: 1, tracking: null, tabular: false,
|
|
};
|
|
const out = { interface: root } as ResolvedFontRoles;
|
|
for (const role of FONT_ROLE_NAMES) {
|
|
if (role === 'interface') continue;
|
|
const spec = font.roles[role];
|
|
const own = roleFamily(spec);
|
|
const from = own.length
|
|
? { stack: fontStack(own), family: own, inherited: false, google: spec !== 'inherit' && spec.source === 'google' ? own[0]! : null }
|
|
: role === 'mono' ? { stack: mono, family: [] as string[], inherited: true, google: null }
|
|
: { stack: root.stack, family: root.family, inherited: true, google: root.google };
|
|
out[role] = {
|
|
...from,
|
|
weight: spec === 'inherit' ? null : spec.weight ?? null,
|
|
size: spec === 'inherit' ? 1 : spec.size ?? 1,
|
|
tracking: spec === 'inherit' ? null : spec.tracking ?? null,
|
|
tabular: spec !== 'inherit' && !!spec.tabular,
|
|
};
|
|
}
|
|
return out;
|
|
}
|
|
|
|
/**
|
|
* A named font stack offered by the panel's pickers. `key` names its translated label
|
|
* (`wb.fonts.choice.*`); `label` is the English one. A site adds its own font first (X: "X's Chirp",
|
|
* an empty family that keeps the site's type).
|
|
*/
|
|
export type FontChoice = { id: string; label: string; key?: string; family: string[] };
|
|
/** Font choices offered by the panel; any installed family can also be named in theme JSON. */
|
|
export const FONT_CHOICES: FontChoice[] = [
|
|
{ id: 'geist', label: 'Geist', family: ['Geist', ...SYSTEM_SANS] },
|
|
{ id: 'geist-mono', label: 'Geist Mono', family: ['Geist Mono', 'Cascadia Mono', 'Consolas', 'Menlo', 'ui-monospace', 'monospace'] },
|
|
{ id: 'system', label: 'System UI', key: 'wb.fonts.choice.system', family: SYSTEM_SANS },
|
|
{ id: 'helvetica', label: 'Helvetica / Arial', family: ['Helvetica Neue', 'Helvetica', 'Arial', 'sans-serif'] },
|
|
{ id: 'humanist', label: 'Humanist (Segoe, Avenir)', key: 'wb.fonts.choice.humanist', family: ['Avenir Next', 'Segoe UI Variable Text', 'Segoe UI', 'sans-serif'] },
|
|
{ id: 'rounded', label: 'Rounded', key: 'wb.fonts.choice.rounded', family: ['ui-rounded', 'SF Pro Rounded', 'Nunito', 'Bahnschrift', 'Segoe UI', 'sans-serif'] },
|
|
{ id: 'serif', label: 'Serif (Charter, Georgia)', key: 'wb.fonts.choice.serif', family: ['Charter', 'Iowan Old Style', 'Georgia', 'Cambria', 'serif'] },
|
|
{ id: 'mono', label: 'System mono', key: 'wb.fonts.choice.mono', family: ['Cascadia Mono', 'SF Mono', 'Consolas', 'Menlo', 'ui-monospace', 'monospace'] },
|
|
];
|
|
/** The choice whose stack is exactly `family` in `choices`, or `custom`. */
|
|
export const fontChoiceOf = (family: string[], choices: readonly FontChoice[] = FONT_CHOICES) => choices.find(choice => choice.family.join('|') === family.join('|'))?.id ?? 'custom';
|
|
|
|
// ---------------------------------------------------------------------------------------------
|
|
// Backgrounds
|
|
|
|
const svgUrl = (svg: string) => `url("data:image/svg+xml,${encodeURIComponent(svg)}")`;
|
|
|
|
/**
|
|
* The site's page background. A site's `<html>` and `<body>` are often one viewport tall while the
|
|
* content overflows them (X's timeline), so a background painted on both had `<body>` paint its own
|
|
* copy over its box, which scrolls away: after a partial scroll the gradient/glow showed only below a hard seam. Now
|
|
* `<html>` holds the plain page color, `<body>` is transparent (beating, by specificity, the
|
|
* palette's `html,body{background-color}` and its `[style^="background-color: …"]` remap of the
|
|
* inline color X puts on `<body>`) and every layer sits on one viewport-sized fixed
|
|
* layer behind all of the page (`z-index:-1` in the root stacking context), with no `fixed` attachments.
|
|
*/
|
|
export function pageBackgroundCss(background: Background, page: string): string[] {
|
|
const out = [`html:root{background:${page} !important}`, `html:root body{background:transparent !important}`];
|
|
if (background.kind !== 'none') {
|
|
out.push(`html:root::before{content:"";position:fixed;inset:0;z-index:-1;pointer-events:none;contain:strict;background:${backgroundLayers(background, page, false)}}`);
|
|
}
|
|
return out;
|
|
}
|
|
|
|
/**
|
|
* CSS `background` layers for the page canvas (behind the site's columns). `attach` keeps the `fixed`
|
|
* attachments for a box that scrolls (the Theme Builder preview); the site's page gets the layers without
|
|
* them, on one viewport-sized fixed layer (`pageBackgroundCss`).
|
|
*/
|
|
export function backgroundLayers(background: Background, page: string, attach = true): string {
|
|
const fixed = attach ? ' fixed' : '';
|
|
switch (background.kind) {
|
|
case 'gradient': {
|
|
const glow = background.glow ? `radial-gradient(1200px 600px at 50% -10%, ${rgba(background.glow, 0.55)}, transparent 70%), ` : '';
|
|
return `${glow}linear-gradient(${background.angle}deg, ${background.from}, ${background.to})${fixed}, ${page}`;
|
|
}
|
|
case 'pattern': {
|
|
const { ink, opacity: a, size: s } = background;
|
|
const c = rgba(ink, a);
|
|
switch (background.pattern) {
|
|
case 'dots': return `radial-gradient(${c} 1px, transparent 1.6px) 0 0 / ${s}px ${s}px, ${page}`;
|
|
case 'grid': return `linear-gradient(${c} 1px, transparent 1px) 0 0 / ${s}px ${s}px, linear-gradient(90deg, ${c} 1px, transparent 1px) 0 0 / ${s}px ${s}px, ${page}`;
|
|
case 'diagonal': return `repeating-linear-gradient(135deg, ${c} 0 1px, transparent 1px ${s}px), ${page}`;
|
|
case 'scanlines': return `repeating-linear-gradient(0deg, ${c} 0 1px, transparent 1px ${s}px), radial-gradient(ellipse at 50% 40%, ${rgba(ink, a * 1.6)}, transparent 70%)${fixed}, ${page}`;
|
|
case 'paper': return `${svgUrl(`<svg xmlns="http://www.w3.org/2000/svg" width="${s}" height="${s}"><filter id="n"><feTurbulence type="fractalNoise" baseFrequency=".85" numOctaves="3" stitchTiles="stitch"/><feColorMatrix values="0 0 0 0 ${hexToRgb(ink).map(v => (v / 255).toFixed(3)).join(' 0 0 0 0 ')} 0 0 0 ${(a * 2.2).toFixed(3)} 0"/></filter><rect width="100%" height="100%" filter="url(#n)"/></svg>`)} 0 0 / ${s}px ${s}px, ${page}`;
|
|
case 'clouds': return [
|
|
`radial-gradient(${s}px ${Math.round(s * 0.42)}px at 12% 22%, ${c}, transparent 70%)${fixed}`,
|
|
`radial-gradient(${Math.round(s * 1.3)}px ${Math.round(s * 0.5)}px at 86% 12%, ${c}, transparent 70%)${fixed}`,
|
|
`radial-gradient(${Math.round(s * 1.1)}px ${Math.round(s * 0.4)}px at 78% 70%, ${c}, transparent 70%)${fixed}`,
|
|
`radial-gradient(${Math.round(s * 0.9)}px ${Math.round(s * 0.36)}px at 18% 82%, ${c}, transparent 70%)${fixed}`,
|
|
`linear-gradient(180deg, ${mix(page, '#ffffff', 0.25)}, ${page} 60%)${fixed}`, page,
|
|
].join(', ');
|
|
}
|
|
return page;
|
|
}
|
|
case 'image': {
|
|
const scrim = `linear-gradient(${rgba(page, background.dim)}, ${rgba(page, background.dim)})${fixed}`;
|
|
return background.fit === 'tile' ? `${scrim}, url("${background.url}") 0 0 / auto repeat, ${page}` : `${scrim}, url("${background.url}") center / cover no-repeat${fixed}, ${page}`;
|
|
}
|
|
default: return page;
|
|
}
|
|
}
|