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

package/src/utils/index.ts

@@ -23,9 +23,12 @@ import {
 import { hasBindingToken } from './iterator-utils';
 import { isCustomThemeType } from '../custom/types';
 import {
-  BREAKPOINT_FALLBACKS,
+  type CustomBreakpoint,
   MOBILE_MEDIA_QUERY,
-  TABLET_MEDIA_QUERY
+  TABLET_MEDIA_QUERY,
+  baseBreakpointOf,
+  customBreakpointMediaQuery,
+  fallbackChainOf
 } from './breakpoints';
 import {
   isSectionMaxWidthToken,
@@ -329,13 +332,11 @@ export const getResponsiveValue = (
     // 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;
-      }
+    // does not run for them and they resolve exactly as they always have. A
+    // custom breakpoint reads the built-in one it stands on.
+    for (const next of fallbackChainOf(breakpoint)) {
+      const inherited = responsiveValue[next];
+      if (inherited !== undefined) return inherited;
     }
 
     if (responsiveValue.desktop !== undefined) return responsiveValue.desktop;
@@ -851,17 +852,15 @@ const isAuthored = (value: unknown): value is string | number =>
  */
 const resolveEntryValue = (
   entry: ResponsiveEntry,
-  breakpoint: string
+  breakpoint: string,
+  customBreakpoints?: CustomBreakpoint[]
 ): 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;
-    }
+  for (const next of fallbackChainOf(breakpoint, customBreakpoints)) {
+    const inherited = entry[next as keyof ResponsiveEntry];
+    if (inherited !== undefined) return inherited;
   }
 
   return entry.desktop;
@@ -974,14 +973,31 @@ const formatCSSValue = (property: string, value: string | number): string => {
   return String(value);
 };
 
+/** The helper keys the hover rules are built from. */
+const HOVER_HELPER_KEYS = [
+  'hover-color',
+  'hover-opacity',
+  'hover-flex',
+  'hover-child-flex'
+];
+
 const generateElementCSS = (
   selector: string,
   rawStyles: ResponsiveStyles,
   targetBreakpoint?: string,
-  options?: { treatHelperKeysAsCss?: boolean }
+  options?: {
+    treatHelperKeysAsCss?: boolean;
+    /**
+     * The theme's custom breakpoints. Passed in rather than read from the
+     * browser registry because the live stylesheet is built on the server.
+     */
+    customBreakpoints?: CustomBreakpoint[];
+  }
 ): string => {
   if (!rawStyles || Object.keys(rawStyles).length === 0) return '';
 
+  const customBreakpoints = options?.customBreakpoints ?? [];
+
   // Bound values belong to the per-row resolution, not to the shared rule.
   const styles = stripBoundStyleValues(
     rawStyles as Record<string, unknown>
@@ -997,22 +1013,41 @@ const generateElementCSS = (
     return styles[kebabKey] ?? styles[camelKey];
   };
 
+  // `getResponsiveValue` with this theme's custom breakpoints in view: their own
+  // value, and otherwise whatever the built-in breakpoint they stand on reads.
+  const valueAt = (
+    entry: unknown,
+    breakpoint: string,
+    fallback: unknown
+  ): unknown => {
+    const custom = customBreakpoints.find((bp) => bp.name === breakpoint);
+
+    if (custom && entry && typeof entry === 'object' && !Array.isArray(entry)) {
+      const own = (entry as Record<string, unknown>)[breakpoint];
+      if (own !== undefined) return own;
+
+      return getResponsiveValue(entry, baseBreakpointOf(custom), fallback);
+    }
+
+    return getResponsiveValue(entry, breakpoint, fallback);
+  };
+
   const getBackgroundAlpha = (breakpoint: string): number | null => {
     const entry = getStyleEntry('background-opacity');
-    const value = entry ? getResponsiveValue(entry, breakpoint, '100') : '100';
+    const value = entry ? valueAt(entry, breakpoint, '100') : '100';
     return clampAlpha(value, 100);
   };
 
   const getHoverAlpha = (breakpoint: string): number | null => {
     const entry = getStyleEntry('hover-opacity');
-    const value = entry ? getResponsiveValue(entry, breakpoint, '100') : '100';
+    const value = entry ? valueAt(entry, breakpoint, '100') : '100';
     return clampAlpha(value, 100);
   };
 
   const getHoverColor = (breakpoint: string): string | null => {
     const entry = getStyleEntry('hover-color');
     const value = entry
-      ? getResponsiveValue(entry, breakpoint, 'var(--theme-secondary)')
+      ? valueAt(entry, breakpoint, 'var(--theme-secondary)')
       : undefined;
     if (value === undefined || value === null || value === '') return null;
     return String(value);
@@ -1021,7 +1056,7 @@ const generateElementCSS = (
   const getHoverFlex = (breakpoint: string): string | null => {
     const entry = getStyleEntry('hover-flex');
     const value = entry
-      ? getResponsiveValue(entry, breakpoint, undefined)
+      ? valueAt(entry, breakpoint, undefined)
       : undefined;
     if (value === undefined || value === null || value === '') return null;
     return String(value);
@@ -1030,7 +1065,7 @@ const generateElementCSS = (
   const getHoverChildFlex = (breakpoint: string): string | null => {
     const entry = getStyleEntry('hover-child-flex');
     const value = entry
-      ? getResponsiveValue(entry, breakpoint, undefined)
+      ? valueAt(entry, breakpoint, undefined)
       : undefined;
     if (value === undefined || value === null || value === '') return null;
     return String(value);
@@ -1120,7 +1155,8 @@ const generateElementCSS = (
         // canvas show a tablet the device never renders.
         const breakpointValue = resolveEntryValue(
           responsiveValue,
-          targetBreakpoint
+          targetBreakpoint,
+          customBreakpoints
         );
         if (
           breakpointValue !== undefined &&
@@ -1230,6 +1266,9 @@ const generateElementCSS = (
   const desktopStyles: string[] = [];
   const mobileStyles: string[] = [];
   const tabletStyles: string[] = [];
+  const customStyles = new Map<string, string[]>(
+    customBreakpoints.map((bp) => [bp.name, []])
+  );
 
   /**
    * The declaration value one breakpoint would produce for one property, by
@@ -1405,6 +1444,23 @@ const generateElementCSS = (
           tabletStyles.push(`  ${cssProperty}: ${formattedTablet}`);
         }
       }
+
+      // A custom breakpoint writes only what it sets itself; everything else
+      // in its range is already painted by the rules above.
+      customBreakpoints.forEach((bp) => {
+        const own = (responsiveValue as Record<string, unknown>)[bp.name];
+        if (!isAuthored(own)) return;
+
+        const formatted = declarationValue(
+          property,
+          cssProperty,
+          bp.name,
+          own
+        );
+        if (formatted) {
+          customStyles.get(bp.name)?.push(`  ${cssProperty}: ${formatted}`);
+        }
+      });
     } else {
       if (cssProperty === 'background-color' && typeof value === 'string') {
         const backgroundAlpha = getBackgroundAlpha('desktop');
@@ -1463,6 +1519,32 @@ const generateElementCSS = (
     css += `${TABLET_MEDIA_QUERY} {\n${tabletDeclarations}${tabletHoverCss}}\n`;
   }
 
+  // Last of all: a custom range overrides whichever built-in rules match inside
+  // it, and at equal specificity it is source order that lets it. Nothing is
+  // written for a theme without custom breakpoints, so its stylesheet is the
+  // one it always was.
+  customBreakpoints.forEach((bp) => {
+    const declarations = customStyles.get(bp.name) ?? [];
+    const setsHover = HOVER_HELPER_KEYS.some((key) => {
+      const entry = getStyleEntry(key);
+      return (
+        !!entry &&
+        typeof entry === 'object' &&
+        isAuthored((entry as Record<string, unknown>)[bp.name])
+      );
+    });
+    const hoverCss = setsHover ? buildHoverCss(bp.name, '  ') : '';
+
+    if (declarations.length === 0 && !hoverCss) return;
+
+    const rule =
+      declarations.length > 0
+        ? `  ${selector} {\n  ${declarations.join(';\n  ')};\n  }\n`
+        : '';
+
+    css += `${customBreakpointMediaQuery(bp)} {\n${rule}${hoverCss}}\n`;
+  });
+
   return css;
 };
 
@@ -1477,7 +1559,8 @@ const generateElementCSS = (
 export const generatePartCSS = (
   blockSelector: string,
   styles: Record<string, unknown>,
-  targetBreakpoint?: string
+  targetBreakpoint?: string,
+  customBreakpoints?: CustomBreakpoint[]
 ): string => {
   const { parts } = splitPartStyles(styles);
   if (parts.length === 0) return '';
@@ -1492,7 +1575,7 @@ export const generatePartCSS = (
       selectors.join(',\n'),
       bucket.styles as ResponsiveStyles,
       targetBreakpoint,
-      { treatHelperKeysAsCss: true }
+      { treatHelperKeysAsCss: true, customBreakpoints }
     );
 
     if (!rules) return;
@@ -1540,7 +1623,8 @@ const generateRootStateCSS = (
    * stateless rule does — and the guard has to be placed per state expression,
    * which is why the flag travels here instead of a finished selector.
    */
-  targetsInnerRoot = false
+  targetsInnerRoot = false,
+  customBreakpoints?: CustomBreakpoint[]
 ): string => {
   const { rootStates } = splitPartStyles(styles);
   if (rootStates.length === 0) return '';
@@ -1562,7 +1646,7 @@ const generateRootStateCSS = (
       // `:<state>/opacity` the editor offers is dropped on the floor. A state
       // BUCKET has no such helper: there it is a real CSS property, exactly as
       // it is on a part, which is why `generatePartCSS` has always passed this.
-      { treatHelperKeysAsCss: true }
+      { treatHelperKeysAsCss: true, customBreakpoints }
     );
 
     if (!rules) return;
@@ -1581,11 +1665,28 @@ const generateRootStateCSS = (
   return css;
 };
 
+/**
+ * The canvas target as one of the three built-in breakpoints, for the emitters
+ * that know only those: a custom breakpoint becomes the band it stands on.
+ */
+const builtInTargetOf = (
+  targetBreakpoint: string | undefined,
+  customBreakpoints: CustomBreakpoint[]
+): string | undefined => {
+  const custom = targetBreakpoint
+    ? customBreakpoints.find((bp) => bp.name === targetBreakpoint)
+    : undefined;
+
+  return custom ? baseBreakpointOf(custom) : targetBreakpoint;
+};
+
 const collectBlockCSS = (
   blocks: Block[],
-  targetBreakpoint?: string
+  targetBreakpoint?: string,
+  customBreakpoints: CustomBreakpoint[] = []
 ): string => {
   let css = '';
+  const hatchBreakpoint = builtInTargetOf(targetBreakpoint, customBreakpoints);
 
   blocks.forEach((block) => {
     // A block that IS or CONTAINS the checkout flow outlet has the real
@@ -1630,7 +1731,8 @@ const collectBlockCSS = (
         css += generateElementCSS(
           rootSelectors.join(',\n'),
           root,
-          targetBreakpoint
+          targetBreakpoint,
+          { customBreakpoints }
         );
       }
 
@@ -1640,10 +1742,16 @@ const collectBlockCSS = (
         selector,
         blockStyles,
         targetBreakpoint,
-        targetsInnerRoot
+        targetsInnerRoot,
+        customBreakpoints
       );
 
-      css += generatePartCSS(selector, blockStyles, targetBreakpoint);
+      css += generatePartCSS(
+        selector,
+        blockStyles,
+        targetBreakpoint,
+        customBreakpoints
+      );
     }
 
     if (block.properties) {
@@ -1653,7 +1761,7 @@ const collectBlockCSS = (
       const customCss = buildCustomCss(
         block.properties as Record<string, unknown>,
         selector,
-        targetBreakpoint
+        hatchBreakpoint
       );
 
       css += guardsCheckoutFlow ? stripHidingCustomCss(customCss) : customCss;
@@ -1664,7 +1772,7 @@ const collectBlockCSS = (
       const partCustomCss = buildPartCustomCss(
         block.properties as Record<string, unknown>,
         selector,
-        targetBreakpoint
+        hatchBreakpoint
       );
 
       css += guardsCheckoutFlow
@@ -1673,7 +1781,11 @@ const collectBlockCSS = (
     }
 
     if (block.blocks && block.blocks.length > 0) {
-      css += collectBlockCSS(block.blocks, targetBreakpoint);
+      css += collectBlockCSS(
+        block.blocks,
+        targetBreakpoint,
+        customBreakpoints
+      );
     }
   });
 
@@ -1682,15 +1794,22 @@ const collectBlockCSS = (
 
 export const generateThemeCSS = (
   sections: Section[],
-  targetBreakpoint?: string
+  targetBreakpoint?: string,
+  /** The theme's custom breakpoints (`readCustomBreakpoints`). */
+  customBreakpoints: CustomBreakpoint[] = []
 ): string => {
+  // The custom-CSS hatch and the scoped line breaks know the three built-in
+  // bands only. On the canvas a custom breakpoint shows them as the band it
+  // stands on does, which is also what its range shows on the live site.
+  const hatchBreakpoint = builtInTargetOf(targetBreakpoint, customBreakpoints);
+
   // First, and outside every section selector: the rules are global by nature
   // (a `<br>` scoped to the phone means the same thing wherever it was typed),
   // and they must lose a specificity tie to anything a section or block emits
   // for itself, which source order settles. Emitted only when the composition
   // actually carries a scoped break — see utils/line-breaks.ts.
   let css = compositionUsesScopedLineBreaks(sections)
-    ? buildLineBreakCss(targetBreakpoint)
+    ? buildLineBreakCss(hatchBreakpoint)
     : '';
 
   sections.forEach((section) => {
@@ -1745,7 +1864,8 @@ export const generateThemeCSS = (
           css += generateElementCSS(
             sectionSelector,
             resolvesOwnMaxWidth ? band : resolveSectionMaxWidthTokens(band),
-            targetBreakpoint
+            targetBreakpoint,
+            { customBreakpoints }
           );
         }
 
@@ -1757,7 +1877,8 @@ export const generateThemeCSS = (
           css += generateElementCSS(
             `${sectionSelector} > [${SECTION_CONTENT_ATTRIBUTE}]`,
             content as ResponsiveStyles,
-            targetBreakpoint
+            targetBreakpoint,
+            { customBreakpoints }
           );
         }
       }
@@ -1765,10 +1886,17 @@ export const generateThemeCSS = (
       css += generateRootStateCSS(
         sectionSelector,
         sectionStyles,
-        targetBreakpoint
+        targetBreakpoint,
+        false,
+        customBreakpoints
       );
 
-      css += generatePartCSS(sectionSelector, sectionStyles, targetBreakpoint);
+      css += generatePartCSS(
+        sectionSelector,
+        sectionStyles,
+        targetBreakpoint,
+        customBreakpoints
+      );
     }
 
     if (section.properties) {
@@ -1778,14 +1906,18 @@ export const generateThemeCSS = (
       const customCss = buildCustomCss(
         section.properties as Record<string, unknown>,
         sectionSelector,
-        targetBreakpoint
+        hatchBreakpoint
       );
 
       css += guardsCheckoutFlow ? stripHidingCustomCss(customCss) : customCss;
     }
 
     if (section.blocks && section.blocks.length > 0) {
-      css += collectBlockCSS(section.blocks, targetBreakpoint);
+      css += collectBlockCSS(
+        section.blocks,
+        targetBreakpoint,
+        customBreakpoints
+      );
     }
   });
 

package/src/utils/property-switches.ts

@@ -41,7 +41,7 @@
 
 import type { Block } from '../theme-block';
 import type { Section } from '../theme-section';
-import { BREAKPOINT_FALLBACKS } from './breakpoints';
+import { fallbackChainOf } from './breakpoints';
 
 export const VISIBLE_WHEN_PROPERTY = 'visibleWhenProperty';
 export const HOVER_REVEAL_WHEN_PROPERTY = 'hoverRevealWhenProperty';
@@ -95,7 +95,7 @@ const readResponsive = (value: unknown, breakpoint: string): unknown => {
   }
 
   const record = value as Properties;
-  const chain = [breakpoint, ...(BREAKPOINT_FALLBACKS[breakpoint] ?? []), 'desktop'];
+  const chain = [breakpoint, ...fallbackChainOf(breakpoint), 'desktop'];
 
   for (const key of chain) {
     if (record[key] !== undefined) return record[key];

package/src/utils/section-content-width.ts

@@ -1,4 +1,4 @@
-import { BREAKPOINTS, BREAKPOINT_FALLBACKS } from './breakpoints';
+import { BREAKPOINTS, fallbackChainOf } from './breakpoints';
 
 /**
  * How wide the CONTENT of a band is allowed to get, as opposed to how wide the
@@ -73,7 +73,7 @@ const at = (value: unknown, breakpoint: string): unknown => {
   const own = value[breakpoint];
   if (own !== undefined) return own;
 
-  for (const next of BREAKPOINT_FALLBACKS[breakpoint] ?? []) {
+  for (const next of fallbackChainOf(breakpoint)) {
     if (value[next] !== undefined) return value[next];
   }
 

package/src/utils/visibility-rules.ts

@@ -1,6 +1,6 @@
 import { Block } from '../theme-block';
 import { Section } from '../theme-section';
-import { BREAKPOINT_FALLBACKS } from './breakpoints';
+import { fallbackChainOf } from './breakpoints';
 import { containsCheckoutOutlet } from './checkout-safety';
 import { devWarn } from './dev-warn';
 
@@ -87,10 +87,10 @@ export const isBreakpointAllowed = (
 ): boolean => {
   if (allowed.includes(breakpoint)) return true;
 
-  const chain = BREAKPOINT_FALLBACKS[breakpoint];
-  if (!chain) return false;
-
-  return chain.some((next) => allowed.includes(next));
+  // A custom breakpoint the list does not name answers as the built-in one it
+  // stands on, the way an unticked-because-it-did-not-exist tablet answers as
+  // mobile: adding a breakpoint must not hide what was already showing there.
+  return fallbackChainOf(breakpoint).some((next) => allowed.includes(next));
 };
 
 export interface VisibilityRuleContext {
@@ -548,7 +548,7 @@ const readResponsive = (value: unknown, breakpoint?: string): unknown => {
   const record = value as Record<string, unknown>;
   const chain = [
     breakpoint,
-    ...(breakpoint ? BREAKPOINT_FALLBACKS[breakpoint] ?? [] : []),
+    ...(breakpoint ? fallbackChainOf(breakpoint) : []),
     'desktop'
   ];