@uniweb/theming 0.1.15 → 0.2.0

package/package.json

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

package/src/section-overrides.js

@@ -12,32 +12,7 @@ import { generatePalettes } from './shade-generator.js'
 import { normalizeTokenValue } from './normalize.js'
 
 /**
- * Check if a block has any section-level overrides worth emitting.
- *
- * @param {Object} standardOptions - Block's standardOptions
- * @returns {boolean}
- */
-function hasOverrides(standardOptions) {
-  if (!standardOptions) return false
-
-  const { colors, foundationStyles } = standardOptions
-
-  if (foundationStyles && Object.keys(foundationStyles).length > 0) return true
-  if (!colors) return false
-
-  const hasColors =
-    colors.colors?.light && Object.keys(colors.colors.light).length > 0
-  const hasElements =
-    colors.elements &&
-    Object.values(colors.elements).some(
-      (ctx) => ctx && Object.keys(ctx).length > 0
-    )
-  return hasColors || hasElements
-}
-
-/**
- * Build CSS variable declarations for base palette overrides.
- * Base palette is context-independent — always stored under the 'light' key.
+ * Build CSS variable declarations for base palette overrides — context-independent.
  *
  * @param {Object} baseColors - e.g. { primary: "#3b82f6", accent: "#f59e0b" }
  * @returns {string[]} CSS declaration lines
@@ -75,7 +50,7 @@ function buildElementVars(elements) {
 }
 
 /**
- * Build CSS variable declarations for foundation style overrides.
+ * Build CSS variable declarations for variable overrides — a section's `vars`, a component's.
  *
  * @param {Object} styles - e.g. { "border-radius": "0.5rem" }
  * @returns {string[]} CSS declaration lines
@@ -92,13 +67,12 @@ function buildFoundationVars(styles) {
 }
 
 /**
- * Split foundation styles into flat (context-independent) and
- * context-keyed (color/gradient) values.
+ * Split variables into flat (context-independent) and context-keyed (color/gradient) values.
  *
  * Flat values: { "radius-xl": "1.5rem" }
  * Context-keyed values: { "colorful-bg": { light: "linear-gradient(...)", dark: "..." } }
  *
- * @param {Object} styles - Foundation styles object
+ * @param {Object} styles - a section's `vars`
  * @returns {{ flat: Object, contexts: Object }} - flat styles + { light: {...}, dark: {...} }
  */
 function splitFoundationStyles(styles) {
@@ -145,8 +119,21 @@ function buildRule(selector, vars) {
  * Works with both Block instances and plain data objects — only reads:
  * - block.stableId || block.id — for CSS selector
  * - block.themeName — '' for Auto, 'light'/'medium'/'dark' for Pinned
- * - block.standardOptions — { colors, foundationStyles }
+ * - block.themeOverrides — the section's `theme:`, as @uniweb/core normalizes it:
+ *   `{ colors, contexts, vars, tokens }` — a palette, tokens per color context, the
+ *   foundation's variables, and tokens for the section in any context
  * - block.componentVars — merged meta.js defaults + frontmatter overrides
+ * - block.childBlocks — child sections get the same, at any depth: rendered as sections,
+ *   they carry the `#section-{id}` these rules select [2026-09-28]
+ *
+ * ⛔ An editor's older envelope, `block.standardOptions` — `{ colors, foundationStyles }` — is
+ * no longer read (2026-09-28): an editor writes the section's `theme`, and @uniweb/core no longer
+ * sets it.
+ *
+ * ⭐ Which context's values apply, for the section's `theme`: a pinned section uses its own
+ * context's; a section that follows the site (Auto) uses `light` under a light scheme and
+ * `dark` under `.scheme-dark` — two rules, so no knowledge of whether the site can go dark
+ * is needed. A context's own token beats one written beside `mode`, being more specific.
  *
  * @param {Array<Object>} blocks - Block data objects
  * @param {Object} appearance - Theme appearance config
@@ -158,59 +145,53 @@ export function buildSectionOverrides(blocks, appearance = {}) {
   if (!blocks || blocks.length === 0) return ''
 
   let css = ''
-
   for (const block of blocks) {
-    const hasStandardOverrides = hasOverrides(block.standardOptions)
-    const hasComponentVars = block.componentVars && Object.keys(block.componentVars).length > 0
-
-    if (!hasStandardOverrides && !hasComponentVars) continue
-
-    const { colors, foundationStyles } = block.standardOptions || {}
-    const sectionId = block.stableId || block.id
-    const selector = `#section-${sectionId}`
-
-    const isAuto = !block.themeName
-    const hasToggle = appearance.allowToggle
-
-    // Base palette is context-independent (always under 'light' key)
-    const paletteVars = buildPaletteVars(colors?.colors?.light)
-
-    // Split foundation styles: flat (context-independent) + context-keyed (color/gradient)
-    const { flat: flatFoundation, contexts: ctxFoundation } = splitFoundationStyles(foundationStyles)
-    const foundationVars = buildFoundationVars(flatFoundation)
-
-    // Component-level CSS vars are context-independent
-    const compVars = buildFoundationVars(block.componentVars)
-
-    if (isAuto && hasToggle) {
-      // Dual rules: light-scoped elements + dark-scoped elements
-      const lightElementVars = buildElementVars(colors?.elements?.light)
-      const darkElementVars = buildElementVars(colors?.elements?.dark)
-
-      // Context-aware foundation vars (color/gradient types)
-      const lightFoundationCtx = buildFoundationVars(ctxFoundation.light)
-      const darkFoundationCtx = buildFoundationVars(ctxFoundation.dark)
-
-      // Context-independent rule: palette + flat foundation + component vars (apply in both schemes)
-      const sharedVars = [...paletteVars, ...foundationVars, ...compVars]
-      css += buildRule(selector, sharedVars)
-
-      // Light-only overrides (elements + context-aware foundation vars)
-      css += buildRule(`:root:not(.scheme-dark) ${selector}`, [...lightElementVars, ...lightFoundationCtx])
+    css += buildBlockRules(block, appearance || {})
+    if (Array.isArray(block.childBlocks) && block.childBlocks.length > 0) {
+      css += buildSectionOverrides(block.childBlocks, appearance)
+    }
+  }
+  return css
+}
 
-      // Dark-only overrides (elements + context-aware foundation vars)
-      css += buildRule(`.scheme-dark ${selector}`, [...darkElementVars, ...darkFoundationCtx])
+/**
+ * The rules for one section: declarations for any scheme, and for an Auto section under a
+ * light and under a dark scheme.
+ */
+function buildBlockRules(block, appearance) {
+  const selector = `#section-${block.stableId || block.id}`
+  const isAuto = !block.themeName
+  const always = []
+  const light = []
+  const dark = []
+
+  // The component's variables: `meta.js` defaults with the section's values over them.
+  always.push(...buildFoundationVars(block.componentVars))
+
+  // The section's `theme:` — theme.yml's keys, scoped to the section.
+  const theme = block.themeOverrides
+  const themeDark = []
+  if (theme) {
+    const { flat, contexts: ctxVars } = splitFoundationStyles(theme.vars)
+    always.push(...buildPaletteVars(theme.colors), ...buildFoundationVars(flat), ...buildElementVars(theme.tokens))
+    if (isAuto) {
+      light.push(...buildElementVars(theme.contexts?.light), ...buildFoundationVars(ctxVars.light))
+      themeDark.push(...buildElementVars(theme.contexts?.dark), ...buildFoundationVars(ctxVars.dark))
+      dark.push(...themeDark)
     } else {
-      // Single context: when toggle is off, always use 'light' bucket
-      // (overrides are context-independent); when toggle is on, use pinned context
-      const ctx = hasToggle ? (block.themeName || 'light') : 'light'
-      const elementVars = buildElementVars(colors?.elements?.[ctx])
-      const ctxFoundationVars = buildFoundationVars(ctxFoundation[ctx])
-
-      const allVars = [...paletteVars, ...elementVars, ...foundationVars, ...compVars, ...ctxFoundationVars]
-      css += buildRule(selector, allVars)
+      always.push(...buildElementVars(theme.contexts?.[block.themeName]), ...buildFoundationVars(ctxVars[block.themeName]))
     }
   }
 
-  return css
+  return (
+    buildRule(selector, always) +
+    buildRule(`:root:not(.scheme-dark) ${selector}`, light) +
+    buildRule(`.scheme-dark ${selector}`, dark) +
+    // A site that follows the visitor's system goes dark through a media query before any
+    // class is set — as the theme's own dark tokens do (`generateDarkSchemeCSS`) — so the
+    // section's dark values follow it there too. Same specificity as the light rule, later.
+    (appearance.default === 'system' && themeDark.length > 0
+      ? `@media (prefers-color-scheme: dark) {\n${buildRule(`:root:not(.scheme-light) ${selector}`, themeDark)}}\n`
+      : '')
+  )
 }