@akinon/pz-theme 2.0.36-rc.0 → 2.0.36

package/src/utils/index.ts

@@ -5,8 +5,19 @@ import {
   neutralizeStyleTagBreakout,
   escapeCssAttributeValue
 } from './css-safety';
+import { buildPartSelectors, splitPartStyles } from './part-styles';
+import { buildCustomCss } from './custom-css';
+import { hasBindingToken } from './iterator-utils';
+import {
+  BREAKPOINT_FALLBACKS,
+  MOBILE_MEDIA_QUERY,
+  TABLET_MEDIA_QUERY
+} from './breakpoints';
 
 export * from './publish-window';
+export * from './part-styles';
+export * from './custom-css';
+export * from './breakpoints';
 
 export type ImageLoadingStrategy = 'eager' | 'lazy';
 export type ImageFetchPriority = 'high' | 'auto' | 'low';
@@ -196,6 +207,20 @@ export const getResponsiveValue = (
     const responsiveValue = value as Record<string, unknown>;
     const matched = responsiveValue[breakpoint];
     if (matched !== undefined) return matched;
+
+    // Nothing authored here, so fall through the way the emitted cascade does:
+    // a tablet reads the mobile value before it reads the desktop one, because
+    // the mobile rule is the one that covers 768-1023 when no tablet rule was
+    // emitted. `desktop` and `mobile` have no intermediate step, so this loop
+    // does not run for them and they resolve exactly as they always have.
+    const chain = BREAKPOINT_FALLBACKS[breakpoint];
+    if (chain) {
+      for (const next of chain) {
+        const inherited = responsiveValue[next];
+        if (inherited !== undefined) return inherited;
+      }
+    }
+
     if (responsiveValue.desktop !== undefined) return responsiveValue.desktop;
     return fallback;
   }
@@ -251,13 +276,59 @@ const kebabToCamel = (str: string): string => {
   return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
 };
 
+/**
+ * A style value carrying a binding token (`{{item.badgeColor}}`) is an
+ * instruction the iterator resolves per row, not a CSS value. It is removed
+ * before emission for two reasons: a token that reached the stylesheet would
+ * write a declaration the browser throws away (so an unresolved binding must
+ * leave the property unset, not half-written), and nothing resembling a token
+ * should ever be interpolated into a `<style>` element.
+ *
+ * Styles with no token are returned by reference, so every composition that
+ * renders today produces byte-identical CSS.
+ */
+const stripBoundStyleValues = <T extends Record<string, unknown>>(
+  styles: T
+): T => {
+  let changed = false;
+  const stripped: Record<string, unknown> = {};
+
+  Object.entries(styles).forEach(([key, value]) => {
+    if (hasBindingToken(value)) {
+      changed = true;
+      return;
+    }
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      const entries = Object.entries(value as Record<string, unknown>);
+      if (
+        entries.some(([, breakpointValue]) => hasBindingToken(breakpointValue))
+      ) {
+        changed = true;
+        const kept = entries.filter(
+          ([, breakpointValue]) => !hasBindingToken(breakpointValue)
+        );
+        if (kept.length > 0) {
+          stripped[key] = Object.fromEntries(kept);
+        }
+        return;
+      }
+    }
+
+    stripped[key] = value;
+  });
+
+  return changed ? (stripped as T) : styles;
+};
+
 export const getCSSStyles = (
-  styles?: Record<string, unknown>,
+  rawStyles?: Record<string, unknown>,
   themeSettings?: ThemeSettings,
   breakpoint: string = 'desktop'
 ): React.CSSProperties => {
-  if (!styles) return {};
+  if (!rawStyles) return {};
 
+  const styles = stripBoundStyleValues(rawStyles);
   const cssStyles: Record<string, string | number> = {};
 
   const normalizeKey = (key: string): string => {
@@ -377,22 +448,62 @@ interface ResponsiveStyles {
   [key: string]:
     | {
         desktop?: string | number;
+        tablet?: string | number;
         mobile?: string | number;
       }
     | string
     | number;
 }
 
+type ResponsiveEntry = {
+  desktop?: string | number;
+  tablet?: string | number;
+  mobile?: string | number;
+};
+
+/** Authored at all, as the generator has always judged it. */
+const isAuthored = (value: unknown): value is string | number =>
+  value !== undefined && value !== null && value !== '';
+
+/**
+ * The value a breakpoint resolves to inside a responsive entry, following the
+ * same chain as `getResponsiveValue` — so the stylesheet and the value readers
+ * cannot disagree about what "nothing authored here" means.
+ */
+const resolveEntryValue = (
+  entry: ResponsiveEntry,
+  breakpoint: string
+): string | number | undefined => {
+  const own = entry[breakpoint as keyof ResponsiveEntry];
+  if (own !== undefined) return own;
+
+  const chain = BREAKPOINT_FALLBACKS[breakpoint];
+  if (chain) {
+    for (const next of chain) {
+      const inherited = entry[next as keyof ResponsiveEntry];
+      if (inherited !== undefined) return inherited;
+    }
+  }
+
+  return entry.desktop;
+};
+
 interface Block {
   id: string;
   styleSourceId?: string;
   styles?: ResponsiveStyles;
+  /** Set by blocks that name their real root with `data-part="root"`. */
+  stylesTargetRoot?: boolean;
+  // Only read for the scoped custom-CSS escape hatch; the rest of a block's
+  // properties never reach the stylesheet.
+  properties?: Record<string, unknown>;
   blocks?: Block[];
 }
 
 interface Section {
   id: string;
   styles?: ResponsiveStyles;
+  properties?: Record<string, unknown>;
   blocks?: Block[];
 }
 
@@ -472,10 +583,21 @@ const formatCSSValue = (property: string, value: string | number): string => {
 
 const generateElementCSS = (
   selector: string,
-  styles: ResponsiveStyles,
-  targetBreakpoint?: string
+  rawStyles: ResponsiveStyles,
+  targetBreakpoint?: string,
+  options?: { treatHelperKeysAsCss?: boolean }
 ): string => {
-  if (!styles || Object.keys(styles).length === 0) return '';
+  if (!rawStyles || Object.keys(rawStyles).length === 0) return '';
+
+  // Bound values belong to the per-row resolution, not to the shared rule.
+  const styles = stripBoundStyleValues(
+    rawStyles as Record<string, unknown>
+  ) as ResponsiveStyles;
+
+  // `opacity` and friends are helper keys on a block root, feeding the
+  // hover/background-alpha maths rather than being emitted directly. A named
+  // part has no such helper, so there they mean the CSS property.
+  const helperKeysAreCss = options?.treatHelperKeysAsCss === true;
 
   const getStyleEntry = (kebabKey: string): unknown => {
     const camelKey = kebabToCamel(kebabKey);
@@ -580,27 +702,33 @@ const generateElementCSS = (
 
     // Skip non-CSS helper keys.
     if (
-      cssProperty === 'text-opacity' ||
-      cssProperty === 'background-opacity' ||
-      cssProperty === 'hover-opacity' ||
-      cssProperty === 'hover-color' ||
-      cssProperty === 'hover-flex' ||
-      cssProperty === 'hover-child-flex' ||
-      cssProperty === 'opacity'
+      !helperKeysAreCss &&
+      (cssProperty === 'text-opacity' ||
+        cssProperty === 'background-opacity' ||
+        cssProperty === 'hover-opacity' ||
+        cssProperty === 'hover-color' ||
+        cssProperty === 'hover-flex' ||
+        cssProperty === 'hover-child-flex' ||
+        cssProperty === 'opacity')
     ) {
       return;
     }
 
     if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-      const responsiveValue = value as {
-        desktop?: string | number;
-        mobile?: string | number;
-      };
+      // `ResponsiveEntry`, not an inline copy of it: the copies predated the
+      // tablet breakpoint and silently lacked it, so reading `.tablet` here
+      // was a type error only the app build could see.
+      const responsiveValue = value as ResponsiveEntry;
 
       if (targetBreakpoint) {
-        const breakpointValue =
-          responsiveValue[targetBreakpoint as keyof typeof responsiveValue] ??
-          responsiveValue.desktop;
+        // The canvas shows one viewport, so it gets the value that viewport
+        // resolves to — including the tablet -> mobile -> desktop fall-through.
+        // Reading only `[breakpoint] ?? desktop` here is what would make the
+        // canvas show a tablet the device never renders.
+        const breakpointValue = resolveEntryValue(
+          responsiveValue,
+          targetBreakpoint
+        );
         if (
           breakpointValue !== undefined &&
           breakpointValue !== null &&
@@ -610,9 +738,7 @@ const generateElementCSS = (
             cssProperty === 'background-color' &&
             typeof breakpointValue === 'string'
           ) {
-            const backgroundAlpha = getBackgroundAlpha(
-              targetBreakpoint === 'mobile' ? 'mobile' : 'desktop'
-            );
+            const backgroundAlpha = getBackgroundAlpha(targetBreakpoint);
             if (backgroundAlpha !== null) {
               if (backgroundAlpha === 0) {
                 cssStyles.push(`  ${cssProperty}: transparent`);
@@ -691,8 +817,11 @@ const generateElementCSS = (
   });
 
   if (targetBreakpoint) {
-    const breakpointKey = targetBreakpoint === 'mobile' ? 'mobile' : 'desktop';
-    const hoverCss = buildHoverCss(breakpointKey);
+    // Passed straight through rather than folded to desktop/mobile: the hover
+    // helpers read through `getResponsiveValue`, which already knows where a
+    // breakpoint looks when it has nothing of its own. For 'desktop' and
+    // 'mobile' this resolves to what the fold produced.
+    const hoverCss = buildHoverCss(targetBreakpoint);
 
     if (cssStyles.length > 0) {
       return `${selector} {\n${cssStyles.join(';\n')};\n}\n${hoverCss}`;
@@ -707,6 +836,32 @@ const generateElementCSS = (
 
   const desktopStyles: string[] = [];
   const mobileStyles: string[] = [];
+  const tabletStyles: string[] = [];
+
+  /**
+   * The declaration value one breakpoint would produce for one property, by
+   * the same rules the desktop and mobile arms below apply inline. Only the
+   * tablet arm calls it, so the two older arms keep emitting the bytes they
+   * always emitted; the tablet arm uses it twice — once for its own value and
+   * once for the value it would inherit — to decide whether a rule is worth
+   * writing at all.
+   */
+  const declarationValue = (
+    property: string,
+    cssProperty: string,
+    breakpoint: string,
+    raw: string | number
+  ): string => {
+    if (cssProperty === 'background-color' && typeof raw === 'string') {
+      const backgroundAlpha = getBackgroundAlpha(breakpoint);
+      if (backgroundAlpha !== null) {
+        if (backgroundAlpha === 0) return 'transparent';
+        return colorToRgba(raw, backgroundAlpha) || raw;
+      }
+    }
+
+    return formatCSSValue(property, raw);
+  };
 
   Object.entries(styles).forEach(([property, value]) => {
     if (value === undefined || value === null) return;
@@ -715,22 +870,23 @@ const generateElementCSS = (
 
     // Skip non-CSS helper keys.
     if (
-      cssProperty === 'text-opacity' ||
-      cssProperty === 'background-opacity' ||
-      cssProperty === 'hover-opacity' ||
-      cssProperty === 'hover-color' ||
-      cssProperty === 'hover-flex' ||
-      cssProperty === 'hover-child-flex' ||
-      cssProperty === 'opacity'
+      !helperKeysAreCss &&
+      (cssProperty === 'text-opacity' ||
+        cssProperty === 'background-opacity' ||
+        cssProperty === 'hover-opacity' ||
+        cssProperty === 'hover-color' ||
+        cssProperty === 'hover-flex' ||
+        cssProperty === 'hover-child-flex' ||
+        cssProperty === 'opacity')
     ) {
       return;
     }
 
     if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-      const responsiveValue = value as {
-        desktop?: string | number;
-        mobile?: string | number;
-      };
+      // `ResponsiveEntry`, not an inline copy of it: the copies predated the
+      // tablet breakpoint and silently lacked it, so reading `.tablet` here
+      // was a type error only the app build could see.
+      const responsiveValue = value as ResponsiveEntry;
 
       if (
         responsiveValue.desktop !== undefined &&
@@ -822,6 +978,40 @@ const generateElementCSS = (
           }
         }
       }
+
+      // Tablet, last, and only when something is authored here. That guard is
+      // what makes every composition published before this breakpoint existed
+      // emit the exact bytes it emitted before: with no tablet key there is no
+      // tablet declaration, so there is no tablet rule.
+      if (isAuthored(responsiveValue.tablet)) {
+        const formattedTablet = declarationValue(
+          property,
+          cssProperty,
+          'tablet',
+          responsiveValue.tablet
+        );
+
+        // What 768-1023 would show without this rule: the mobile declaration
+        // if one was authored (its query covers the band), otherwise desktop's.
+        // Matching it means the rule would change nothing, so it is not
+        // written — the same reasoning that already suppresses a mobile value
+        // equal to desktop.
+        const inheritedRaw = isAuthored(responsiveValue.mobile)
+          ? responsiveValue.mobile
+          : responsiveValue.desktop;
+        const inherited = isAuthored(inheritedRaw)
+          ? declarationValue(
+              property,
+              cssProperty,
+              isAuthored(responsiveValue.mobile) ? 'mobile' : 'desktop',
+              inheritedRaw
+            )
+          : '';
+
+        if (formattedTablet && formattedTablet !== inherited) {
+          tabletStyles.push(`  ${cssProperty}: ${formattedTablet}`);
+        }
+      }
     } else {
       if (cssProperty === 'background-color' && typeof value === 'string') {
         const backgroundAlpha = getBackgroundAlpha('desktop');
@@ -851,14 +1041,80 @@ const generateElementCSS = (
 
   css += buildHoverCss('desktop');
 
+  const mobileHoverCss = buildHoverCss('mobile', '  ');
+
   if (mobileStyles.length > 0) {
-    const mobileHoverCss = buildHoverCss('mobile', '  ');
 
-    css += `@media (max-width: 1023px) {\n  ${selector} {\n  ${mobileStyles.join(
+    css += `${MOBILE_MEDIA_QUERY} {\n  ${selector} {\n  ${mobileStyles.join(
       ';\n  '
     )};\n  }\n${mobileHoverCss}}\n`;
   }
 
+  // After the mobile query, never before it. Both match at 900px, both carry
+  // the same selector and therefore the same specificity, so the one written
+  // second is the one that wins — that ordering is the entire mechanism by
+  // which a tablet value beats the mobile value it falls back to.
+  const tabletHoverCss = buildHoverCss('tablet', '  ');
+  // What is already painting at 900px: the mobile query when one was written,
+  // otherwise the base rule. A helper key (hover-*, background-opacity) never
+  // reaches `tabletStyles`, so keying the query on that array alone dropped a
+  // tablet-authored hover entirely.
+  const inheritedHoverCss =
+    mobileStyles.length > 0 ? mobileHoverCss : buildHoverCss('desktop', '  ');
+
+  if (tabletStyles.length > 0 || tabletHoverCss !== inheritedHoverCss) {
+
+    const tabletDeclarations =
+      tabletStyles.length > 0
+        ? `  ${selector} {\n  ${tabletStyles.join(';\n  ')};\n  }\n`
+        : '';
+
+    css += `${TABLET_MEDIA_QUERY} {\n${tabletDeclarations}${tabletHoverCss}}\n`;
+  }
+
+  return css;
+};
+
+/**
+ * Rules for the named parts inside a functional block.
+ *
+ * The element being targeted almost always carries the renderer's own inline
+ * defaults, and inline styles outrank any stylesheet — so a designer's
+ * override is emitted `!important`. Without it the override would be written,
+ * saved, shown in the panel, and then quietly do nothing.
+ */
+const generatePartCSS = (
+  blockSelector: string,
+  styles: Record<string, unknown>,
+  targetBreakpoint?: string
+): string => {
+  const { parts } = splitPartStyles(styles);
+  if (parts.length === 0) return '';
+
+  let css = '';
+
+  parts.forEach((bucket) => {
+    const selectors = buildPartSelectors(blockSelector, bucket);
+    if (selectors.length === 0) return;
+
+    const rules = generateElementCSS(
+      selectors.join(',\n'),
+      bucket.styles as ResponsiveStyles,
+      targetBreakpoint,
+      { treatHelperKeysAsCss: true }
+    );
+
+    if (!rules) return;
+
+    css += rules.replace(
+      /^(\s*)([a-z-]+):\s*([^;\n]+);/gm,
+      (line, indent, property, value) =>
+        value.includes('!important')
+          ? line
+          : `${indent}${property}: ${value} !important;`
+    );
+  });
+
   return css;
 };
 
@@ -873,7 +1129,37 @@ const collectBlockCSS = (
       const selector = `[data-block-id="${escapeCssAttributeValue(
         block.styleSourceId || block.id
       )}"]`;
-      css += generateElementCSS(selector, block.styles, targetBreakpoint);
+      // Root styles ignore part keys, so a part override never leaks onto the
+      // block wrapper (a padding meant for the dropdown would otherwise
+      // reposition the whole block).
+      const { root } = splitPartStyles(block.styles);
+
+      if (Object.keys(root).length > 0) {
+        // `data-block-id` sits on the designer wrapper, not on the element the
+        // renderer actually draws — so a padding or border set on a functional
+        // block stopped at a transparent div and never reached the control.
+        // A block that names its real root with `data-part="root"` gets its
+        // own styles routed there instead. Blocks that do not are untouched,
+        // which is what keeps published compositions rendering as before.
+        const rootSelector = block.stylesTargetRoot
+          ? `${selector} [data-part="root"]`
+          : selector;
+
+        css += generateElementCSS(rootSelector, root, targetBreakpoint);
+      }
+
+      css += generatePartCSS(selector, block.styles, targetBreakpoint);
+    }
+
+    if (block.properties) {
+      const selector = `[data-block-id="${escapeCssAttributeValue(
+        block.styleSourceId || block.id
+      )}"]`;
+      css += buildCustomCss(
+        block.properties as Record<string, unknown>,
+        selector,
+        targetBreakpoint
+      );
     }
 
     if (block.blocks && block.blocks.length > 0) {
@@ -891,11 +1177,36 @@ export const generateThemeCSS = (
   let css = '';
 
   sections.forEach((section) => {
+    const sectionSelector = `[data-section-id="${escapeCssAttributeValue(
+      section.id
+    )}"]`;
+
     if (section.styles && Object.keys(section.styles).length > 0) {
-      const selector = `[data-section-id="${escapeCssAttributeValue(
-        section.id
-      )}"]`;
-      css += generateElementCSS(selector, section.styles, targetBreakpoint);
+      // Sections went straight to generateElementCSS, so a part key on a
+      // section was emitted as the invalid declaration `dropdown/color:`.
+      const { root: sectionRoot } = splitPartStyles(section.styles);
+
+      if (Object.keys(sectionRoot).length > 0) {
+        css += generateElementCSS(
+          sectionSelector,
+          sectionRoot,
+          targetBreakpoint
+        );
+      }
+
+      css += generatePartCSS(
+        sectionSelector,
+        section.styles,
+        targetBreakpoint
+      );
+    }
+
+    if (section.properties) {
+      css += buildCustomCss(
+        section.properties as Record<string, unknown>,
+        sectionSelector,
+        targetBreakpoint
+      );
     }
 
     if (section.blocks && section.blocks.length > 0) {