@uniweb/theming 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/theming",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Theming utilities for the Uniweb platform — shade generation, CSS generation, theme processing",
   "type": "module",
   "exports": {

package/src/css-generator.js

@@ -210,54 +210,36 @@ const GENERIC_FAMILIES = new Set([
   'inherit', 'initial', 'revert', 'unset',
 ])
 
-// Foundation `font-*` vars that are CSS longhands, not typefaces — never
-// treat their value as a family to load.
-const NON_FAMILY_FONT_VARS = new Set([
-  'font-weight', 'font-style', 'font-size', 'font-stretch',
-  'font-feature-settings', 'font-variation-settings', 'font-variant',
-  'font-kerning', 'font-optical-sizing', 'font-synthesis',
-  'font-size-adjust', 'font-smoothing', 'font-palette', 'font-language-override',
-])
+// Font-role classification (isFontVar, NON_FAMILY_FONT_VARS) and the default
+// role selectors now live in processor.js, which resolves the whole font-role
+// namespace (built-in roles + foundation redefinitions/additions) into config.
 
 /**
- * Extract the font family names the site actually references.
+ * Extract the font family names to load, from a resolved font-role map.
  *
- * Two sources count as "used":
- *   1. The `body`/`heading`/`mono` slots the user explicitly configured
- *      (tracked via _userSlots from the processor). Default system stacks are
- *      ignored so they don't trigger unnecessary font loading.
- *   2. Foundation `font-*` vars (e.g. an editorial `font-serif`). A foundation
- *      can declare a themeable typeface beyond the three built-in roles; the
- *      site sets its value and loads it with `fonts.import` / `fonts.faces`.
- *      Without counting these, such a family is filtered out as "unused" and
- *      never loads — capping a foundation at the three role slots.
+ * A role contributes its family only when the processor flagged it `load`
+ * (site-set or foundation-declared — not a bare framework default like
+ * `system-ui`). Generic keywords and numeric tokens are skipped, so a role's
+ * fallback stack never triggers an unnecessary fetch.
  *
- * @param {Object} fonts - Font configuration (may carry _userSlots)
- * @param {Object} [foundationVars] - Resolved foundation vars (name → { default } | value)
- * @returns {Set<string>} Lowercase family names referenced by the site
+ * @param {Object} fontRoles - Resolved roles: name → { value, applyTo, apply, load }
+ * @returns {Set<string>} Lowercase family names to load (@font-face / import filter)
  */
-function extractUsedFamilies(fonts, foundationVars = {}) {
+function extractUsedFamilies(fontRoles = {}) {
   const used = new Set()
 
   const addFamiliesFrom = (value) => {
     if (typeof value !== 'string') return
     for (const segment of value.split(',')) {
       const name = segment.trim().replace(/^["']|["']$/g, '').toLowerCase()
-      // Skip generics, empties, and numeric/length tokens (a weight "600" or
-      // size "1rem" a non-family font-* var might carry).
+      // Skip generics, empties, and numeric/length tokens.
       if (!name || GENERIC_FAMILIES.has(name) || /^\d/.test(name)) continue
       used.add(name)
     }
   }
 
-  const slots = fonts._userSlots || ['body', 'heading', 'mono']
-  for (const slot of slots) {
-    addFamiliesFrom(fonts[slot])
-  }
-
-  for (const [name, config] of Object.entries(foundationVars)) {
-    if (!name.startsWith('font-') || NON_FAMILY_FONT_VARS.has(name)) continue
-    addFamiliesFrom(typeof config === 'object' ? config?.default : config)
+  for (const role of Object.values(fontRoles)) {
+    if (role && role.load) addFamiliesFrom(role.value)
   }
 
   return used
@@ -309,14 +291,15 @@ function isGoogleFontsUrl(url) {
 /**
  * Generate font CSS and external link tags.
  *
- * @param {Object} fonts - Font configuration
+ * @param {Object} fontRoles - Resolved font roles (name → { value, applyTo, apply, load })
+ * @param {Object} fonts - Font loading config (import[] / faces[])
  * @returns {{ css: string, links: string }} css for <style>, links for <head>
  */
-function generateFontCSS(fonts = {}, foundationVars = {}) {
+function generateFontCSS(fontRoles = {}, fonts = {}) {
   const cssLines = []
   const linkTags = []
 
-  const usedFamilies = extractUsedFamilies(fonts, foundationVars)
+  const usedFamilies = extractUsedFamilies(fontRoles)
 
   // --- @font-face rules from faces[] (filtered to used families) ---
   // Also generate <link rel="preload"> hints so browsers fetch fonts early
@@ -402,16 +385,12 @@ function generateFontCSS(fonts = {}, foundationVars = {}) {
     }
   }
 
-  // --- :root font variables ---
+  // --- :root font variables (one --font-<name> per role, emitted once) ---
   const fontVars = []
-  if (fonts.body) {
-    fontVars.push(`  --font-body: ${fonts.body};`)
-  }
-  if (fonts.heading) {
-    fontVars.push(`  --font-heading: ${fonts.heading};`)
-  }
-  if (fonts.mono) {
-    fontVars.push(`  --font-mono: ${fonts.mono};`)
+  for (const [name, role] of Object.entries(fontRoles)) {
+    if (role.value) {
+      fontVars.push(`  --font-${name}: ${role.value};`)
+    }
   }
 
   if (fontVars.length > 0) {
@@ -421,26 +400,18 @@ function generateFontCSS(fonts = {}, foundationVars = {}) {
   }
 
   // --- Apply font families to elements ---
-  // Defining --font-* on :root is not enough — something must actually set
-  // `font-family` on rendered elements, the same way colors get an application
-  // rule ([id^="section-"] { background-color: var(--section) }). Without this
-  // the font vars are orphaned and text never picks them up, even though the
-  // vars are set and the @import/@font-face load. Only apply slots the SITE
-  // explicitly set (fonts._userSlots) so a foundation's own default typography
-  // is left untouched when theme.yml doesn't override that slot.
-  const userSlots = new Set(fonts._userSlots || [])
+  // Defining --font-* on :root is not enough — something must set `font-family`
+  // on rendered elements, the same way colors get an application rule
+  // ([id^="section-"] { background-color: var(--section) }). The processor has
+  // already resolved which roles apply (`role.apply`): a built-in role applies
+  // only when the site set it (don't stomp a foundation's own typography with
+  // system-ui); a foundation-owned/redefined role applies always via its
+  // `applyTo` selectors.
   const applyRules = []
-  if (userSlots.has('body')) {
-    applyRules.push('body { font-family: var(--font-body); }')
-  }
-  if (userSlots.has('heading')) {
-    // Only the prominent headings — display/heading faces are drawn for large
-    // sizes; h4–h6 usually render at or near body size where a display face
-    // reads awkwardly, so they stay in the body font.
-    applyRules.push('h1, h2, h3 { font-family: var(--font-heading); }')
-  }
-  if (userSlots.has('mono')) {
-    applyRules.push('code, pre, kbd, samp { font-family: var(--font-mono); }')
+  for (const [name, role] of Object.entries(fontRoles)) {
+    if (!role.apply || !role.applyTo?.length) continue
+    const selector = role.applyTo.join(', ')
+    applyRules.push(`${selector} { font-family: var(--font-${name}); }`)
   }
   if (applyRules.length > 0) {
     cssLines.push('')
@@ -518,6 +489,7 @@ export function generateThemeCSS(config = {}) {
     colors = DEFAULT_COLORS,
     contexts = {},
     fonts = {},
+    fontRoles = {},
     appearance = {},
     foundationVars = {},
     colorVars = {},
@@ -525,10 +497,11 @@ export function generateThemeCSS(config = {}) {
 
   const sections = []
 
-  // 1. Font face rules and variables (links returned separately)
-  //    foundationVars is passed so families referenced by a foundation `font-*`
-  //    var (e.g. an editorial `font-serif`) survive the used-family filter.
-  const fontResult = generateFontCSS(fonts, foundationVars)
+  // 1. Font face rules and variables (links returned separately). Font roles are
+  //    resolved by the processor; `fonts` carries only import[] / faces[] here.
+  //    Font-typed vars are already split out of `foundationVars`, so the generic
+  //    foundation-var emission below never double-writes a --font-<name>.
+  const fontResult = generateFontCSS(fontRoles, fonts)
   if (fontResult.css) {
     sections.push('/* Typography */\n' + fontResult.css)
   }

package/src/processor.js

@@ -56,7 +56,53 @@ const DEFAULT_APPEARANCE = {
 const DEFAULT_FONTS = {
   body: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
   heading: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-  mono: 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Monaco, Consolas, monospace',
+  code: 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Monaco, Consolas, monospace',
+}
+
+/**
+ * Default application selectors for the three built-in font roles. These are
+ * *defaults*: a foundation can redefine a role's `applyTo` (or add new roles)
+ * via a `type: 'font'` var, so the roles and their selectors are one editable
+ * font-var namespace, not a fixed contract. `heading` is scoped to h1–h3 (h4–h6
+ * render near body size, where a display face reads awkwardly); `code` (formerly
+ * `mono`) owns `--font-code`.
+ */
+const DEFAULT_FONT_ROLES = {
+  body: ['body'],
+  heading: ['h1', 'h2', 'h3'],
+  code: ['code', 'pre', 'kbd', 'samp'],
+}
+
+// Foundation `font-*` vars that are CSS longhands, not typefaces to load.
+const NON_FAMILY_FONT_VARS = new Set([
+  'font-weight', 'font-style', 'font-size', 'font-stretch',
+  'font-feature-settings', 'font-variation-settings', 'font-variant',
+  'font-kerning', 'font-optical-sizing', 'font-synthesis',
+  'font-size-adjust', 'font-smoothing', 'font-palette', 'font-language-override',
+])
+
+/**
+ * A foundation var is a themeable typeface (font role) when it declares
+ * `type: 'font'`. Deprecated fallback: a `font-*`-prefixed name that isn't a
+ * known CSS longhand — kept so foundations predating the convention still work.
+ */
+function isFontVar(name, config) {
+  const type = typeof config === 'object' ? config?.type : undefined
+  if (type === 'font') return true
+  return name.startsWith('font-') && !NON_FAMILY_FONT_VARS.has(name)
+}
+
+// A font role's canonical name is bare; `font-X` and `X` are the same role.
+function normalizeFontRoleName(name) {
+  return name.startsWith('font-') ? name.slice(5) : name
+}
+
+// Normalize applyTo to an array of trimmed selectors (or null).
+function normalizeApplyTo(applyTo) {
+  if (applyTo == null) return null
+  const list = Array.isArray(applyTo) ? applyTo : String(applyTo).split(',')
+  const cleaned = list.map((s) => String(s).trim()).filter(Boolean)
+  return cleaned.length ? cleaned : null
 }
 
 /**
@@ -261,7 +307,10 @@ const CONTEXT_AWARE_TYPES = new Set(['color', 'gradient'])
 /**
  * Validate foundation variables configuration
  *
- * Accepts enriched var schema: { default, description, label, type, options, group, globalOnly }
+ * Accepts enriched var schema: { default, description, label, type, options, group, globalOnly, applyTo }
+ * A `type: 'font'` var is a themeable typeface (family loads, schema tags it as
+ * a font); its optional `applyTo` is a list of selectors the framework paints
+ * `font-family: var(--<name>)` onto, like a built-in role.
  *
  * @param {Object} vars - Foundation variables
  * @returns {{ valid: boolean, errors: string[] }}
@@ -478,15 +527,12 @@ export function processTheme(rawConfig = {}, options = {}) {
     contexts[name] = { ...defaultContexts[name], ...normalized }
   }
 
-  // Process fonts
-  const fonts = {
-    ...DEFAULT_FONTS,
-    ...(rawConfig.fonts || {}),
-  }
-  // Track which font slots the user explicitly set (vs inherited defaults).
-  // Used by extractUsedFamilies to avoid loading fonts referenced only in defaults.
-  const userFonts = rawConfig.fonts || {}
-  fonts._userSlots = ['body', 'heading', 'mono'].filter((s) => userFonts[s] !== undefined)
+  // Fonts resolve into the font-role namespace after foundation vars are merged
+  // (below), so a foundation's font vars can redefine/extend the roles. `mono`
+  // is not a built-in role — the code/monospace role is `code`. It flows through
+  // as an ordinary name (a foundation may define a `mono` typeface); a
+  // post-resolution check nudges a site that set `fonts.mono` expecting code.
+  const rawFonts = { ...(rawConfig.fonts || {}) }
 
   // Normalize and process appearance
   const appearance = normalizeAppearance(rawConfig.appearance)
@@ -504,6 +550,80 @@ export function processTheme(rawConfig = {}, options = {}) {
     warnings.push(...foundationValidation.errors)
   }
 
+  // Resolve the font-role namespace. The three roles are framework *defaults*;
+  // a foundation `type: 'font'` var can redefine a role (retarget applyTo /
+  // change the default) or add a new role; the site sets any role's value in
+  // `fonts:` (or `vars:`). Everything lands in one map so each --font-<name> is
+  // emitted once, site-value-wins. Font vars are split OUT of foundationVars so
+  // they aren't also emitted by the generic foundation-var path (which would
+  // double-write --font-<name>, the later foundation default clobbering the site).
+  const fontRoles = {}
+  for (const [name, applyTo] of Object.entries(DEFAULT_FONT_ROLES)) {
+    fontRoles[name] = {
+      value: DEFAULT_FONTS[name],
+      applyTo: [...applyTo],
+      foundationOwned: false,
+      userSet: false,
+    }
+  }
+
+  const nonFontVars = {}
+  for (const [rawName, cfg] of Object.entries(mergedFoundationVars)) {
+    if (!isFontVar(rawName, cfg)) {
+      nonFontVars[rawName] = cfg
+      continue
+    }
+    const name = normalizeFontRoleName(rawName)
+    const cfgObj = typeof cfg === 'object' ? cfg : { default: cfg }
+    const existing = fontRoles[name]
+    fontRoles[name] = {
+      value: cfgObj.default ?? existing?.value,
+      applyTo:
+        cfgObj.applyTo !== undefined
+          ? normalizeApplyTo(cfgObj.applyTo)
+          : existing?.applyTo ?? null,
+      foundationOwned: true,
+      userSet: false,
+    }
+  }
+
+  const FONT_LOADING_KEYS = new Set(['import', 'faces'])
+  for (const [rawName, value] of Object.entries(rawFonts)) {
+    if (FONT_LOADING_KEYS.has(rawName)) continue
+    const name = normalizeFontRoleName(rawName)
+    const existing = fontRoles[name]
+    fontRoles[name] = {
+      value,
+      applyTo: existing?.applyTo ?? null,
+      foundationOwned: existing?.foundationOwned ?? false,
+      userSet: true,
+    }
+  }
+
+  // Per-role application + loading flags. apply: emit the font-family rule when
+  // the role has selectors AND is "intended" (site-set or foundation-owned) —
+  // a bare framework default is never forced onto a foundation's own typography.
+  // load: pull the family through the @font-face / import filter.
+  for (const role of Object.values(fontRoles)) {
+    const intended = role.foundationOwned || role.userSet
+    role.apply = intended && Array.isArray(role.applyTo) && role.applyTo.length > 0
+    role.load = intended
+  }
+
+  // `mono` is no longer aliased to `code`. Nudge a site that set `fonts.mono`
+  // expecting the code font, unless the foundation actually defines a `mono` role.
+  if (rawFonts.mono !== undefined && !fontRoles.mono?.foundationOwned) {
+    warnings.push('theme.yml `fonts.mono` is not a built-in font role — the code/monospace role is `code`. Rename `fonts.mono` → `fonts.code`.')
+  }
+
+  // config.fonts: name→value (for the Theme API) plus import/faces (loading).
+  const fonts = {}
+  if (rawFonts.import !== undefined) fonts.import = rawFonts.import
+  if (rawFonts.faces !== undefined) fonts.faces = rawFonts.faces
+  for (const [name, role] of Object.entries(fontRoles)) {
+    fonts[name] = role.value
+  }
+
   // Process code block theme
   // These values are stored for runtime injection by kit's Code component
   // (not converted to CSS here - enables tree-shaking when code blocks aren't used)
@@ -523,9 +643,10 @@ export function processTheme(rawConfig = {}, options = {}) {
     colors,      // Raw colors for CSS generator
     palettes,    // Generated palettes for Theme class
     contexts,
-    fonts,
+    fonts,       // name→value (+ import/faces) for the Theme API and loading
+    fontRoles,   // resolved font-role map (value/applyTo/apply/load) for CSS gen
     appearance,
-    foundationVars: mergedFoundationVars, // Context-independent vars only
+    foundationVars: nonFontVars, // NON-font vars only (font vars live in fontRoles)
     colorVars,   // Context-aware vars: { light: {...}, dark: {...} }
     code,        // Code block theme for runtime injection
     background,  // Site-level background CSS value