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

package/src/utils/__tests__/custom-breakpoints.test.ts

@@ -0,0 +1,326 @@
+/**
+ * Breakpoints the designer adds next to desktop, tablet and mobile.
+ *
+ * A custom breakpoint is an override layered over the three: inside its range
+ * it paints what it sets itself, and everything else it reads from the
+ * built-in breakpoint it stands on. The tests hold the three readers to that —
+ * the live stylesheet, the canvas and the value readers — and hold a theme
+ * without custom breakpoints to the stylesheet it always had.
+ */
+import {
+  generateThemeCSS,
+  getResponsiveValue,
+  breakpointForViewport,
+  customBreakpointMediaQuery,
+  isNarrowBreakpoint,
+  readCustomBreakpoints,
+  registerCustomBreakpoints,
+  type CustomBreakpoint
+} from '../index';
+import { isBreakpointAllowed } from '../visibility-rules';
+
+const section = (styles: Record<string, unknown>, id = 's1') => [
+  { id, styles } as never
+];
+
+const WIDE: CustomBreakpoint = {
+  name: 'custom-wide',
+  label: 'Wide desktop',
+  width: 1440,
+  minWidth: 1440
+};
+
+const SMALL_PHONE: CustomBreakpoint = {
+  name: 'custom-small',
+  label: 'Small phone',
+  width: 374,
+  maxWidth: 374
+};
+
+const LAPTOP: CustomBreakpoint = {
+  name: 'custom-laptop',
+  label: 'Laptop',
+  width: 1024,
+  minWidth: 1024,
+  maxWidth: 1279
+};
+
+const CUSTOM = [WIDE, LAPTOP, SMALL_PHONE];
+
+/**
+ * What applies at `width` in a stylesheet this generator produced: every rule
+ * carries the same selector, so the last matching declaration wins.
+ */
+const computedAt = (css: string, width: number): Record<string, string> => {
+  const applied: Record<string, string> = {};
+
+  const queryMatches = (prelude: string): boolean => {
+    const max = prelude.match(/max-width:\s*(\d+)px/);
+    const min = prelude.match(/min-width:\s*(\d+)px/);
+    if (max && width > Number(max[1])) return false;
+    if (min && width < Number(min[1])) return false;
+    return true;
+  };
+
+  const readDeclarations = (body: string) => {
+    body.split(';').forEach((declaration) => {
+      const [property, ...rest] = declaration.split(':');
+      if (rest.length === 0) return;
+      const name = property.trim();
+      if (!name || name.startsWith('@')) return;
+      applied[name] = rest.join(':').trim();
+    });
+  };
+
+  let index = 0;
+  while (index < css.length) {
+    const open = css.indexOf('{', index);
+    if (open === -1) break;
+
+    const prelude = css.slice(index, open).trim();
+    let depth = 0;
+    let close = open;
+    for (let i = open; i < css.length; i++) {
+      if (css[i] === '{') depth += 1;
+      else if (css[i] === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          close = i;
+          break;
+        }
+      }
+    }
+
+    const body = css.slice(open + 1, close);
+
+    if (prelude.startsWith('@media')) {
+      if (queryMatches(prelude)) {
+        const innerOpen = body.indexOf('{');
+        if (innerOpen !== -1) {
+          readDeclarations(body.slice(innerOpen + 1, body.indexOf('}')));
+        }
+      }
+    } else if (!prelude.includes(':hover')) {
+      readDeclarations(body);
+    }
+
+    index = close + 1;
+  }
+
+  return applied;
+};
+
+afterEach(() => registerCustomBreakpoints([]));
+
+describe('reading the theme breakpoints', () => {
+  it('keeps the custom entries, widest first, and drops what it cannot use', () => {
+    expect(
+      readCustomBreakpoints([
+        { name: 'desktop', width: 1024 },
+        { name: 'tablet', width: 768 },
+        {
+          name: 'custom-small',
+          label: 'Small phone',
+          width: 374,
+          maxWidth: 374
+        },
+        {
+          name: 'custom-wide',
+          label: 'Wide desktop',
+          width: 1440,
+          minWidth: 1440
+        },
+        { name: 'custom-inverted', minWidth: 900, maxWidth: 600 },
+        { name: '', minWidth: 10 },
+        null,
+        'custom-string'
+      ])
+    ).toEqual([WIDE, SMALL_PHONE]);
+  });
+
+  it('reads the old widget builder shape as a range from its width up', () => {
+    expect(readCustomBreakpoints([{ name: 'large', width: 1600 }])).toEqual([
+      { name: 'large', label: 'large', width: 1600, minWidth: 1600 }
+    ]);
+  });
+
+  it('answers empty for anything that is not a list', () => {
+    expect(readCustomBreakpoints(undefined)).toEqual([]);
+    expect(readCustomBreakpoints({ name: 'custom-wide' })).toEqual([]);
+  });
+
+  it('builds the query from the ends the range has', () => {
+    expect(customBreakpointMediaQuery(WIDE)).toBe('@media (min-width: 1440px)');
+    expect(customBreakpointMediaQuery(SMALL_PHONE)).toBe(
+      '@media (max-width: 374px)'
+    );
+    expect(customBreakpointMediaQuery(LAPTOP)).toBe(
+      '@media (min-width: 1024px) and (max-width: 1279px)'
+    );
+  });
+});
+
+describe('a theme without custom breakpoints', () => {
+  const styles = {
+    padding: { desktop: '40px', tablet: '24px', mobile: '16px' },
+    color: '#111111'
+  };
+
+  it('emits the stylesheet it emitted before', () => {
+    expect(generateThemeCSS(section(styles), undefined, [])).toBe(
+      generateThemeCSS(section(styles))
+    );
+  });
+
+  it('emits the same stylesheet when none of its values address one', () => {
+    expect(generateThemeCSS(section(styles), undefined, CUSTOM)).toBe(
+      generateThemeCSS(section(styles))
+    );
+  });
+});
+
+describe('the live stylesheet', () => {
+  const styles = {
+    padding: {
+      desktop: '40px',
+      mobile: '16px',
+      'custom-wide': '80px',
+      'custom-laptop': '32px',
+      'custom-small': '8px'
+    },
+    color: { desktop: '#111111', 'custom-wide': '#ff0000' }
+  };
+  const css = generateThemeCSS(section(styles), undefined, CUSTOM);
+
+  it('applies each custom value inside its own range only', () => {
+    expect(computedAt(css, 1600)).toEqual({
+      padding: '80px',
+      color: '#ff0000'
+    });
+    expect(computedAt(css, 1440)).toEqual({
+      padding: '80px',
+      color: '#ff0000'
+    });
+    expect(computedAt(css, 1300)).toEqual({
+      padding: '40px',
+      color: '#111111'
+    });
+    expect(computedAt(css, 1100)).toEqual({
+      padding: '32px',
+      color: '#111111'
+    });
+    expect(computedAt(css, 800)).toEqual({ padding: '16px', color: '#111111' });
+    expect(computedAt(css, 390)).toEqual({ padding: '16px', color: '#111111' });
+    expect(computedAt(css, 360)).toEqual({ padding: '8px', color: '#111111' });
+  });
+
+  it('writes the custom rules after the built-in ones', () => {
+    expect(css.indexOf('@media (min-width: 1440px)')).toBeGreaterThan(
+      css.indexOf('@media (max-width: 1023px)')
+    );
+    expect(css.indexOf('@media (max-width: 374px)')).toBeGreaterThan(
+      css.indexOf('@media (max-width: 1023px)')
+    );
+  });
+
+  it('ignores the values of a breakpoint the theme no longer defines', () => {
+    expect(generateThemeCSS(section(styles), undefined, [WIDE])).not.toContain(
+      '374px'
+    );
+    expect(generateThemeCSS(section(styles))).toBe(
+      generateThemeCSS(
+        section({
+          padding: { desktop: '40px', mobile: '16px' },
+          color: { desktop: '#111111' }
+        })
+      )
+    );
+  });
+
+  it('emits a hover authored for a custom breakpoint inside its range', () => {
+    const hoverCss = generateThemeCSS(
+      [
+        {
+          id: 's1',
+          styles: {},
+          blocks: [
+            {
+              id: 'b1',
+              type: 'button',
+              styles: {
+                'hover-color': { desktop: '#000000', 'custom-wide': '#00ff00' }
+              }
+            }
+          ]
+        } as never
+      ],
+      undefined,
+      CUSTOM
+    );
+
+    const wideRule = hoverCss.slice(
+      hoverCss.indexOf('@media (min-width: 1440px)')
+    );
+    expect(wideRule).toContain(':hover');
+    expect(wideRule).toContain('#00ff00');
+  });
+});
+
+describe('the canvas', () => {
+  const styles = {
+    padding: { desktop: '40px', mobile: '16px', 'custom-wide': '80px' }
+  };
+
+  it('shows the custom value when the breakpoint sets one', () => {
+    expect(
+      computedAt(generateThemeCSS(section(styles), 'custom-wide', CUSTOM), 0)
+    ).toEqual({ padding: '80px' });
+  });
+
+  it('shows the band the breakpoint stands on when it sets nothing', () => {
+    // A 374px phone reads the mobile value, not the desktop one.
+    expect(
+      computedAt(generateThemeCSS(section(styles), 'custom-small', CUSTOM), 0)
+    ).toEqual({ padding: '16px' });
+    expect(
+      computedAt(generateThemeCSS(section(styles), 'custom-laptop', CUSTOM), 0)
+    ).toEqual({ padding: '40px' });
+  });
+});
+
+describe('the value readers', () => {
+  beforeEach(() => registerCustomBreakpoints(CUSTOM));
+
+  it('resolve a custom breakpoint through the band it stands on', () => {
+    const value = { desktop: 4, tablet: 3, mobile: 2, 'custom-wide': 6 };
+
+    expect(getResponsiveValue(value, 'custom-wide')).toBe(6);
+    expect(getResponsiveValue(value, 'custom-laptop')).toBe(4);
+    expect(getResponsiveValue(value, 'custom-small')).toBe(2);
+    expect(getResponsiveValue({ desktop: 4 }, 'custom-small')).toBe(4);
+  });
+
+  it('find the breakpoint a viewport is read at', () => {
+    expect(breakpointForViewport(1600)).toBe('custom-wide');
+    expect(breakpointForViewport(1300)).toBe('desktop');
+    expect(breakpointForViewport(1100)).toBe('custom-laptop');
+    expect(breakpointForViewport(900)).toBe('tablet');
+    expect(breakpointForViewport(500)).toBe('mobile');
+    expect(breakpointForViewport(374)).toBe('custom-small');
+  });
+
+  it('call a custom breakpoint narrow when its band is', () => {
+    expect(isNarrowBreakpoint('custom-small')).toBe(true);
+    expect(isNarrowBreakpoint('custom-wide')).toBe(false);
+    expect(isNarrowBreakpoint('custom-unknown')).toBe(false);
+  });
+
+  it('keep visibility lists saved before the breakpoint existed working', () => {
+    expect(isBreakpointAllowed(['desktop', 'mobile'], 'custom-small')).toBe(
+      true
+    );
+    expect(isBreakpointAllowed(['desktop'], 'custom-small')).toBe(false);
+    expect(isBreakpointAllowed(['mobile'], 'custom-wide')).toBe(false);
+    expect(isBreakpointAllowed(['custom-wide'], 'custom-wide')).toBe(true);
+  });
+});

package/src/utils/breakpoints.ts

@@ -65,6 +65,162 @@ export const BREAKPOINT_FALLBACKS: Record<string, BreakpointName[]> = {
   tablet: ['mobile']
 };
 
+/**
+ * A breakpoint the theme defines on top of the three above, in the editor's
+ * breakpoint panel.
+ *
+ * `name` is the key its values are stored under inside every per-breakpoint
+ * object (`{ desktop, mobile, 'custom-…': … }`). It is generated once by the
+ * editor and never changes; what the designer typed is `label`.
+ *
+ * Its values apply to viewports from `minWidth` to `maxWidth`, both inclusive,
+ * either end open. Anything it does not set itself falls back to the built-in
+ * breakpoint it stands on — the band its canvas `width` is in — so a custom
+ * breakpoint is an override layered over the three, never a replacement for
+ * them. The editor's `constants/breakpoints.ts` reads the same entries the
+ * same way; `readCustomBreakpoints` below is the renderer's copy of that
+ * reading.
+ */
+export interface CustomBreakpoint {
+  name: string;
+  label: string;
+  width: number;
+  minWidth?: number;
+  maxWidth?: number;
+}
+
+const isBuiltInName = (name: string): name is BreakpointName =>
+  (BREAKPOINTS as string[]).includes(name);
+
+const isPixelValue = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= 0;
+
+/**
+ * The theme's custom breakpoints, from `theme.breakpoints` as the editor saves
+ * it (`theme_breakpoints` on the `theme-config` widget). Entries named after a
+ * built-in breakpoint only set that breakpoint's canvas width in the editor,
+ * and a malformed entry is dropped on its own rather than taking the rest with
+ * it. An entry with a width and no range — the old widget builder's shape —
+ * applies from its width up.
+ */
+export const readCustomBreakpoints = (raw: unknown): CustomBreakpoint[] => {
+  if (!Array.isArray(raw)) return [];
+
+  return raw
+    .map((entry): CustomBreakpoint | null => {
+      if (!entry || typeof entry !== 'object') return null;
+
+      const record = entry as Record<string, unknown>;
+      const name = typeof record.name === 'string' ? record.name.trim() : '';
+      if (!name || isBuiltInName(name)) return null;
+
+      let minWidth = isPixelValue(record.minWidth)
+        ? record.minWidth
+        : undefined;
+      const maxWidth = isPixelValue(record.maxWidth)
+        ? record.maxWidth
+        : undefined;
+
+      if (minWidth === undefined && maxWidth === undefined) {
+        if (!isPixelValue(record.width)) return null;
+        minWidth = record.width;
+      }
+
+      if (
+        minWidth !== undefined &&
+        maxWidth !== undefined &&
+        minWidth > maxWidth
+      ) {
+        return null;
+      }
+
+      const label =
+        typeof record.label === 'string' && record.label.trim()
+          ? record.label.trim()
+          : name;
+
+      return {
+        name,
+        label,
+        // The canvas width, as the editor computes it: the low edge, or the
+        // top of a range that is open at the bottom.
+        width:
+          minWidth !== undefined && minWidth > 0
+            ? minWidth
+            : maxWidth ?? minWidth ?? 0,
+        ...(minWidth !== undefined ? { minWidth } : {}),
+        ...(maxWidth !== undefined ? { maxWidth } : {})
+      };
+    })
+    .filter((entry): entry is CustomBreakpoint => entry !== null)
+    .sort((a, b) => b.width - a.width);
+};
+
+/** The built-in breakpoint a custom one falls back to. */
+export const baseBreakpointOf = (
+  breakpoint: CustomBreakpoint
+): BreakpointName => breakpointForWidth(breakpoint.width);
+
+/** The media query a custom breakpoint's rules are emitted inside. */
+export const customBreakpointMediaQuery = (
+  breakpoint: CustomBreakpoint
+): string => {
+  const conditions = [
+    breakpoint.minWidth !== undefined && breakpoint.minWidth > 0
+      ? `(min-width: ${breakpoint.minWidth}px)`
+      : '',
+    breakpoint.maxWidth !== undefined
+      ? `(max-width: ${breakpoint.maxWidth}px)`
+      : ''
+  ].filter(Boolean);
+
+  return conditions.length > 0
+    ? `@media ${conditions.join(' and ')}`
+    : '@media all';
+};
+
+/**
+ * The custom breakpoints of the theme on this page, for the readers that only
+ * ever see a value and a breakpoint name (`getResponsiveValue` and the
+ * visibility rules among them).
+ *
+ * Browser only. A server renders at `desktop` and never resolves a custom
+ * key, and a module-level list there would be shared by every request the
+ * process serves. The stylesheet generator is handed its list explicitly for
+ * the same reason.
+ */
+let registeredCustomBreakpoints: CustomBreakpoint[] = [];
+
+export const registerCustomBreakpoints = (
+  breakpoints: CustomBreakpoint[]
+): void => {
+  if (typeof window === 'undefined') return;
+  registeredCustomBreakpoints = breakpoints;
+};
+
+export const getRegisteredCustomBreakpoints = (): CustomBreakpoint[] =>
+  registeredCustomBreakpoints;
+
+/**
+ * Where a breakpoint looks when it has nothing authored of its own, before the
+ * desktop value every reader ends on. A custom breakpoint looks at the built-in
+ * one it stands on, and then wherever that one looks.
+ */
+export const fallbackChainOf = (
+  breakpoint: string,
+  customBreakpoints: CustomBreakpoint[] = registeredCustomBreakpoints
+): string[] => {
+  const builtIn = BREAKPOINT_FALLBACKS[breakpoint];
+  if (builtIn) return builtIn;
+  if (isBuiltInName(breakpoint)) return [];
+
+  const custom = customBreakpoints.find((entry) => entry.name === breakpoint);
+  if (!custom) return [];
+
+  const base = baseBreakpointOf(custom);
+  return [base, ...(BREAKPOINT_FALLBACKS[base] || [])];
+};
+
 /**
  * The mobile query, unchanged and deliberately still `max-width: 1023px`
  * rather than being narrowed to 767. Narrowing it would hand the 768-1023 band
@@ -105,6 +261,23 @@ export const breakpointForWidth = (width: number): BreakpointName => {
   return 'mobile';
 };
 
+/**
+ * The breakpoint a viewport is read at once the theme's custom breakpoints are
+ * counted: the custom one whose range holds the width, otherwise the built-in
+ * band. The editor refuses overlapping ranges, so at most one can match.
+ */
+export const breakpointForViewport = (
+  width: number,
+  customBreakpoints: CustomBreakpoint[] = registeredCustomBreakpoints
+): string => {
+  const custom = customBreakpoints.find(
+    (entry) =>
+      width >= (entry.minWidth ?? 0) && width <= (entry.maxWidth ?? Infinity)
+  );
+
+  return custom ? custom.name : breakpointForWidth(width);
+};
+
 /**
  * "Narrower than desktop" — the question the code that predates the tablet was
  * actually asking whenever it compared against `'mobile'`. Answering it with a
@@ -112,8 +285,27 @@ export const breakpointForWidth = (width: number): BreakpointName => {
  * behaving at 768-1023 exactly as they did when `'mobile'` was the only other
  * value there was.
  */
-export const isNarrowBreakpoint = (breakpoint?: string): boolean =>
-  breakpoint === 'mobile' || breakpoint === 'tablet';
+/**
+ * A registered custom breakpoint as the built-in one it stands on, for the
+ * readers that only know the three — anything else is returned as it is.
+ */
+export const builtInBreakpointOf = (breakpoint: string): string => {
+  const custom = registeredCustomBreakpoints.find(
+    (entry) => entry.name === breakpoint
+  );
+  return custom ? baseBreakpointOf(custom) : breakpoint;
+};
+
+export const isNarrowBreakpoint = (breakpoint?: string): boolean => {
+  if (breakpoint === 'mobile' || breakpoint === 'tablet') return true;
+  if (!breakpoint || breakpoint === 'desktop') return false;
+
+  // A custom breakpoint is as narrow as the band it stands on.
+  const custom = registeredCustomBreakpoints.find(
+    (entry) => entry.name === breakpoint
+  );
+  return custom ? baseBreakpointOf(custom) !== 'desktop' : false;
+};
 
 /**
  * The same two bands as media QUERIES, but as bare media CONDITIONS for a