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

package/CHANGELOG.md

@@ -1,36 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.62-rc.0
-
-### Patch Changes
-
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea4143]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a63]
-- Updated dependencies [e18836b20]
-  - @akinon/next@2.0.62-rc.0
-  - @akinon/theme-contract@2.0.62-rc.0
+## 2.0.62
+
+### Patch Changes
+
+- 583e69c: ZERO-4778: Implement content width feature for sections and add related tests
+  - @akinon/next@2.0.62
+  - @akinon/theme-contract@2.0.62
 
 ## 2.0.61
 

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.62-rc.0",
+  "version": "2.0.62",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.62-rc.0",
+    "@akinon/next": "2.0.62",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.62-rc.0",
+    "@akinon/theme-contract": "2.0.62",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.62-rc.0",
+    "@akinon/next": "2.0.62",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/section-content-box.test.tsx

@@ -0,0 +1,92 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+
+import ThemeSection from '../theme-section';
+import { ThemeSettingsProvider } from '../theme-settings-context';
+import { SECTION_CONTENT_ATTRIBUTE } from '../utils/section-content-width';
+
+/**
+ * The element the content-width rule is written against.
+ *
+ * A section holds its blocks in a wrapper that is `display: contents` — it
+ * generates no box, so the blocks are the section's own children as far as
+ * layout is concerned. That is load-bearing for every page already published: a
+ * section set to Flex arranges its blocks directly through it.
+ *
+ * It is also why the wrapper cannot simply be given a width. These hold the
+ * switch: a box only when the section constrains its content, `contents`
+ * otherwise, and the attribute in both cases so the selector has something
+ * stable to name.
+ */
+
+const section = (styles: Record<string, unknown>) =>
+  ({
+    id: 'section-1',
+    type: 'custom',
+    name: 'Band',
+    label: 'Band',
+    order: 0,
+    hidden: false,
+    properties: {},
+    styles,
+    blocks: [
+      {
+        id: 'text-1',
+        type: 'text',
+        label: 'Heading',
+        value: 'Spring',
+        properties: {},
+        styles: {},
+        order: 0,
+        hidden: false
+      }
+    ]
+  } as never);
+
+const renderSection = (styles: Record<string, unknown>) => {
+  const { container } = render(
+    <ThemeSettingsProvider value={null}>
+      <ThemeSection
+        section={section(styles)}
+        placeholderId="home-body"
+        currentBreakpoint="desktop"
+        isDesigner={false}
+      />
+    </ThemeSettingsProvider>
+  );
+
+  return container.querySelector(`[${SECTION_CONTENT_ATTRIBUTE}]`);
+};
+
+describe('the box a content width is applied to', () => {
+  it('is always named, so the rule has something to select', () => {
+    const box = renderSection({});
+
+    expect(box).not.toBeNull();
+    expect(box?.parentElement?.tagName).toBe('SECTION');
+  });
+
+  it('generates no box until the section constrains its content', () => {
+    // `display: contents` is what today's compositions lay out through.
+    expect(renderSection({})).toHaveClass('contents');
+  });
+
+  it('becomes a real box the moment one is set', () => {
+    const box = renderSection({ 'content-width': '1024px' });
+
+    expect(box).not.toHaveClass('contents');
+    expect(box).toHaveClass('w-full');
+  });
+
+  it('reads a width set on one breakpoint only', () => {
+    expect(renderSection({ 'content-width': { mobile: '640px' } })).toHaveClass(
+      'w-full'
+    );
+  });
+
+  it('stays out of the way when Custom was chosen but nothing typed', () => {
+    expect(renderSection({ 'content-width': 'custom' })).toHaveClass(
+      'contents'
+    );
+  });
+});

package/src/blocks/__tests__/slider-block.test.tsx

@@ -260,3 +260,108 @@ describe('SliderBlock — arrow button geometry', () => {
     ).toBe('28px');
   });
 });
+
+/**
+ * The offsets the panel offers on the arrow's icon block used to reach the
+ * theme JSON and stop there — the button was pinned by `left-4 top-1/2
+ * -translate-y-1/2` and only its size was read. These cover both halves of
+ * honouring them: the value lands inline, and the class default for that axis
+ * gets out of the way instead of fighting it.
+ */
+describe('SliderBlock — arrow button placement', () => {
+  const arrow = (label: string, styles: Record<string, unknown>) =>
+    child(label === 'Left Arrow Icon' ? 'left' : 'right', {
+      type: 'icon',
+      label,
+      styles
+    });
+
+  const renderArrows = (
+    leftStyles: Record<string, unknown>,
+    rightStyles: Record<string, unknown> = {}
+  ) =>
+    render(
+      <SliderBlock
+        {...props({
+          isDesigner: true,
+          block: {
+            ...props().block,
+            blocks: [
+              arrow('Left Arrow Icon', leftStyles),
+              child('s1'),
+              arrow('Right Arrow Icon', rightStyles)
+            ]
+          }
+        })}
+      />
+    );
+
+  const previous = (container: HTMLElement) =>
+    container.querySelector('button[aria-label="Previous"]') as HTMLElement;
+  const next = (container: HTMLElement) =>
+    container.querySelector('button[aria-label="Next"]') as HTMLElement;
+
+  it('falls back to the class defaults when no offset is authored', () => {
+    const { container } = renderArrows({});
+    const button = previous(container);
+
+    expect(button.className).toContain('left-4');
+    expect(button.className).toContain('top-1/2');
+    expect(button.className).toContain('-translate-y-1/2');
+    expect(button.style.left).toBe('');
+  });
+
+  it('honours an authored left, including 0', () => {
+    const { container } = renderArrows({ left: 0 });
+    const button = previous(container);
+
+    expect(button.style.left).toBe('0px');
+    // The class would not override the inline value, but leaving it in place
+    // is what made `right` unreachable below — so it goes.
+    expect(button.className).not.toContain('left-4');
+  });
+
+  it('drops the horizontal default so an authored right is not over-constrained', () => {
+    // left-4 + an inline right + a width is three constraints on one axis, and
+    // CSS resolves that by ignoring the right — the arrow would not move.
+    const { container } = renderArrows({ right: '24px' });
+    const button = previous(container);
+
+    expect(button.style.right).toBe('24px');
+    expect(button.className).not.toContain('left-4');
+  });
+
+  it('drops the centering translate when a vertical offset is authored', () => {
+    const { container } = renderArrows({ top: '0px' });
+    const button = previous(container);
+
+    expect(button.style.top).toBe('0px');
+    expect(button.className).not.toContain('-translate-y-1/2');
+    expect(button.className).not.toContain('top-1/2');
+  });
+
+  it('keeps the vertical default when only a horizontal offset is authored', () => {
+    const { container } = renderArrows({ left: '8px' });
+    const button = previous(container);
+
+    expect(button.className).toContain('top-1/2');
+    expect(button.className).toContain('-translate-y-1/2');
+  });
+
+  it('places each arrow from its own block', () => {
+    const { container } = renderArrows({ left: '10px' }, { right: '90px' });
+
+    expect(previous(container).style.left).toBe('10px');
+    expect(next(container).style.right).toBe('90px');
+    expect(next(container).className).not.toContain('right-4');
+    // The left arrow's own axis default is untouched by the right arrow.
+    expect(previous(container).className).not.toContain('left-4');
+  });
+
+  it('still positions absolutely with a z-index', () => {
+    const { container } = renderArrows({ left: '10px' });
+
+    expect(previous(container).className).toContain('absolute');
+    expect(previous(container).className).toContain('z-10');
+  });
+});

package/src/blocks/slider-block.tsx

@@ -437,12 +437,42 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
     if (radius) geometry.borderRadius = radius;
     else if (Object.keys(corners).length === 0) geometry.borderRadius = '50%';
 
+    // The editor offers these four on the arrow's icon block, but only the
+    // sizes above were ever read — so an authored offset reached the theme
+    // JSON and stopped there, leaving the arrow pinned to the class default
+    // with no feedback that the field did nothing.
+    (['left', 'right', 'top', 'bottom'] as const).forEach((key) => {
+      const value = read(key);
+      if (value) geometry[key] = value;
+    });
+
     return { ...geometry, ...corners };
   };
 
   const leftArrowButtonStyle = arrowGeometry(leftArrowIconBlock);
   const rightArrowButtonStyle = arrowGeometry(rightArrowIconBlock);
 
+  /**
+   * The class defaults step aside per axis for whatever the author set.
+   * An inline `left` already outranks the `left-4` class, but the pair that
+   * would survive is the harmful one: `left-4` alongside an authored `right`
+   * over-constrains the box and CSS drops the `right`, and the centering
+   * translate would shift an authored `top` by half the button's height.
+   */
+  const arrowPlacementClass = (
+    style: React.CSSProperties,
+    horizontalFallback: string
+  ) =>
+    clsx(
+      'absolute z-10',
+      style.left === undefined && style.right === undefined
+        ? horizontalFallback
+        : undefined,
+      style.top === undefined && style.bottom === undefined
+        ? 'top-1/2 -translate-y-1/2'
+        : undefined
+    );
+
   const handleLeftArrowClick = (e: React.MouseEvent) => {
     e.preventDefault();
     e.stopPropagation();
@@ -467,7 +497,7 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
         handleLeftArrowClick(e);
       }}
       className={clsx(
-        'absolute left-4 top-1/2 -translate-y-1/2 z-10',
+        arrowPlacementClass(leftArrowButtonStyle, 'left-4'),
         isDesigner &&
           selectedBlockId === leftArrowIconBlock?.id &&
           'ring-2 ring-blue-500 ring-offset-2'
@@ -507,7 +537,7 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
         handleRightArrowClick(e);
       }}
       className={clsx(
-        'absolute right-4 top-1/2 -translate-y-1/2 z-10',
+        arrowPlacementClass(rightArrowButtonStyle, 'right-4'),
         isDesigner &&
           selectedBlockId === rightArrowIconBlock?.id &&
           'ring-2 ring-blue-500 ring-offset-2'
@@ -631,7 +661,7 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
             <button
               onClick={handleLeftArrowClick}
               className={clsx(
-                'absolute left-4 top-1/2 -translate-y-1/2 z-10',
+                arrowPlacementClass(leftArrowButtonStyle, 'left-4'),
                 selectedBlockId === leftArrowIconBlock?.id &&
                   'ring-2 ring-blue-500 ring-offset-2'
               )}
@@ -662,7 +692,7 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
             <button
               onClick={handleRightArrowClick}
               className={clsx(
-                'absolute right-4 top-1/2 -translate-y-1/2 z-10',
+                arrowPlacementClass(rightArrowButtonStyle, 'right-4'),
                 selectedBlockId === rightArrowIconBlock?.id &&
                   'ring-2 ring-blue-500 ring-offset-2'
               )}

package/src/sections/section-wrapper.tsx

@@ -5,6 +5,7 @@ import ActionToolbar from '../components/action-toolbar';
 import { twMerge } from 'tailwind-merge';
 import clsx from 'clsx';
 import { Section } from '../theme-section';
+import { SECTION_CONTENT_ATTRIBUTE } from '../utils/section-content-width';
 
 import { isTrustedEditorEvent, postToEditor } from '../editor-bridge';
 interface SectionWrapperProps {
@@ -153,7 +154,15 @@ export default function SectionWrapper({
           onRename={onRename}
         />
       )}
-      <div className="relative z-10">{children}</div>
+      {/*
+       * Already a real box, so unlike the generic path this one needs no
+       * switch — only the attribute the content-width rule is written against.
+       * A section that renders through its own component also keeps its own
+       * `display`: this box has always been the thing that carried it.
+       */}
+      <div {...{ [SECTION_CONTENT_ATTRIBUTE]: '' }} className="relative z-10">
+        {children}
+      </div>
     </section>
   );
 }

package/src/theme-section.tsx

@@ -15,6 +15,10 @@ import {
 import { useLocalization } from '@akinon/next/hooks';
 import { devWarn } from './utils/dev-warn';
 import { isNarrowBreakpoint } from './utils/breakpoints';
+import {
+  SECTION_CONTENT_ATTRIBUTE,
+  hasSectionContentWidth
+} from './utils/section-content-width';
 import { safeDeepClone } from './utils/safe-clone';
 
 import { isTrustedEditorEvent, postToEditor } from './editor-bridge';
@@ -120,6 +124,8 @@ export default function ThemeSection({
 
   const sectionRef = useRef<HTMLElement>(null);
 
+  const constrainsContent = hasSectionContentWidth(effectiveSection.styles);
+
   // Bound prices are formatted deep inside the binding walk, which has no
   // React context to read. Publishing the storefront's locale before the
   // bindings resolve is what stops an en-GB brand rendering Turkish number
@@ -1002,7 +1008,19 @@ export default function ThemeSection({
         />
       )}
 
-      <div className={twMerge(clsx('contents'))}>
+      {/*
+       * `display: contents` until the section constrains its content, and a
+       * real box the moment it does. The wrapper has to generate a box to be
+       * given a width at all, but making it one unconditionally would change
+       * every page already published: today the blocks are the section's own
+       * children for layout purposes, so a section set to Flex arranges them
+       * directly. When the box does appear, the section's child layout moves
+       * onto it (splitSectionContentWidth) so that arrangement survives.
+       */}
+      <div
+        {...{ [SECTION_CONTENT_ATTRIBUTE]: '' }}
+        className={twMerge(clsx(constrainsContent ? 'w-full' : 'contents'))}
+      >
         {effectiveSection.blocks
           .sort((a, b) => a.order - b.order)
           .filter((block) => (isDesigner ? true : !block.hidden))

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

@@ -0,0 +1,319 @@
+import { generateThemeCSS } from '../index';
+import {
+  SECTION_CONTENT_ATTRIBUTE,
+  hasSectionContentWidth,
+  splitSectionContentWidth
+} from '../section-content-width';
+import { MOBILE_MEDIA_QUERY, TABLET_MEDIA_QUERY } from '../breakpoints';
+import type { Section } from '../../theme-section';
+
+/**
+ * A band's colour and its measure are two decisions, and a section only had one
+ * control for them. `max-width` lands on the `<section>` itself, so holding the
+ * words to 1024px held the background to 1024px as well; the way round it was
+ * to add one of five prebuilt container sections and rebuild the band inside.
+ *
+ * `content-width` is the second decision. What these assert is the split: the
+ * constraint reaches the box inside the band and nothing else, everything that
+ * draws the band stays on it, and a section that does not use the setting emits
+ * the bytes it always emitted.
+ */
+
+const section = (
+  styles: Record<string, unknown>,
+  over: Partial<Section> = {}
+): Section[] => [
+  {
+    id: 'sec-1',
+    type: 'custom',
+    name: 'Section',
+    label: 'Section',
+    order: 0,
+    hidden: false,
+    properties: {},
+    styles,
+    blocks: [],
+    ...over
+  } as unknown as Section
+];
+
+const BAND_SELECTOR = '[data-section-id="sec-1"]';
+const CONTENT_SELECTOR = `${BAND_SELECTOR} > [${SECTION_CONTENT_ATTRIBUTE}]`;
+
+/**
+ * The declarations of one UNCONDITIONAL rule.
+ *
+ * Anchored to the start of a line, which is what keeps it from returning a
+ * rule nested inside a media query — those are written indented, and matching
+ * one of them would quietly turn "the desktop band declares no width" into
+ * "some breakpoint somewhere does not".
+ */
+const ruleFor = (css: string, selector: string): string => {
+  const escaped = selector.replace(/[[\]().*+?^$|\\{}]/g, '\\$&');
+  return new RegExp(`^${escaped} \\{([^}]*)\\}`, 'm').exec(css)?.[1] ?? '';
+};
+
+describe('content width constrains the content and nothing else', () => {
+  it('writes the width onto the box inside the band, not the band', () => {
+    const css = generateThemeCSS(section({ 'content-width': '1024px' }));
+
+    expect(ruleFor(css, CONTENT_SELECTOR)).toContain('max-width: 1024px');
+    // The band is what a background paints across. A `max-width` here is the
+    // whole bug this setting exists to avoid.
+    expect(ruleFor(css, BAND_SELECTOR)).not.toContain('max-width');
+  });
+
+  it('centres it — a constrained column against the left edge is not what the control means', () => {
+    const rule = ruleFor(
+      generateThemeCSS(section({ 'content-width': '768px' })),
+      CONTENT_SELECTOR
+    );
+
+    expect(rule).toContain('margin-left: auto');
+    expect(rule).toContain('margin-right: auto');
+    // Without it the box is a flex item in any section that arranges its
+    // children, and a flex item shrinks to its content rather than reaching
+    // the width it is being capped at.
+    expect(rule).toContain('width: 100%');
+  });
+
+  it('leaves the background, the border and the padding on the full-width band', () => {
+    const css = generateThemeCSS(
+      section({
+        'content-width': '1024px',
+        'background-color': '#101010',
+        'background-image': 'url(/hero.jpg)',
+        'border-bottom': '1px solid #333',
+        'padding-left': '16px',
+        'padding-right': '16px'
+      })
+    );
+    const band = ruleFor(css, BAND_SELECTOR);
+
+    // Written as rgba: the generator folds the section's background opacity
+    // into the colour before it emits it.
+    expect(band).toContain('background-color: rgba(16, 16, 16, 1)');
+    expect(band).toContain('background-image: url(/hero.jpg)');
+    expect(band).toContain('border-bottom: 1px solid #333');
+    // The padding stays on the band on purpose: the constrained box sits
+    // inside the padding box, so on a screen narrower than the measure it is
+    // the padding that keeps the words off the edge of the phone.
+    expect(band).toContain('padding-left: 16px');
+    expect(ruleFor(css, CONTENT_SELECTOR)).not.toContain('padding');
+  });
+
+  it('never emits the helper keys themselves — neither is CSS', () => {
+    const css = generateThemeCSS(
+      section({ 'content-width': 'custom', 'content-width-custom': '900px' })
+    );
+
+    expect(css).not.toContain('content-width:');
+    expect(ruleFor(css, CONTENT_SELECTOR)).toContain('max-width: 900px');
+  });
+
+  it('reads the camelCase spellings published JSON also carries', () => {
+    const css = generateThemeCSS(
+      section({ contentWidth: 'custom', contentWidthCustom: '60rem' })
+    );
+
+    expect(ruleFor(css, CONTENT_SELECTOR)).toContain('max-width: 60rem');
+    expect(css).not.toContain('contentWidth');
+  });
+
+  it('treats a half-finished custom value as not authored yet', () => {
+    // Choosing Custom and typing nothing is mid-edit, not a decision to go
+    // full width — so nothing is written and the band renders as it did.
+    const css = generateThemeCSS(
+      section({ 'content-width': 'custom', 'content-width-custom': '' })
+    );
+
+    expect(css).not.toContain(SECTION_CONTENT_ATTRIBUTE);
+  });
+});
+
+describe('content width per breakpoint', () => {
+  it('constrains a desktop and lets a phone use the whole screen', () => {
+    const css = generateThemeCSS(
+      section({ 'content-width': { desktop: '1280px', mobile: 'full' } })
+    );
+
+    expect(ruleFor(css, CONTENT_SELECTOR)).toContain('max-width: 1280px');
+    expect(css).toContain(MOBILE_MEDIA_QUERY);
+    // `full` is the editor's word for it and is not CSS. It has to be emitted
+    // as something rather than dropped: a dropped declaration would leave the
+    // desktop rule cascading down onto the breakpoint that opted out of it.
+    expect(css).toContain('max-width: none');
+    expect(css).not.toContain('max-width: full');
+  });
+
+  it('lets a tablet take a measure of its own', () => {
+    const css = generateThemeCSS(
+      section({
+        'content-width': { desktop: '1280px', tablet: '768px', mobile: 'full' }
+      })
+    );
+
+    expect(css).toContain(TABLET_MEDIA_QUERY);
+    // After the mobile query, which is the entire mechanism by which a tablet
+    // beats the value it would otherwise inherit.
+    expect(css.indexOf(TABLET_MEDIA_QUERY)).toBeGreaterThan(
+      css.indexOf(MOBILE_MEDIA_QUERY)
+    );
+    expect(css).toContain('max-width: 768px');
+  });
+
+  it('takes the free-value box per breakpoint too', () => {
+    const css = generateThemeCSS(
+      section({
+        'content-width': { desktop: 'custom', mobile: '640px' },
+        'content-width-custom': { desktop: '1100px' }
+      })
+    );
+
+    expect(ruleFor(css, CONTENT_SELECTOR)).toContain('max-width: 1100px');
+    expect(css).toContain('max-width: 640px');
+  });
+
+  it('emits one rule, not three, when one measure covers every width', () => {
+    const css = generateThemeCSS(section({ 'content-width': '1024px' }));
+
+    expect(css).not.toContain(MOBILE_MEDIA_QUERY);
+    expect(css).not.toContain(TABLET_MEDIA_QUERY);
+  });
+
+  it('resolves to one width on the editor canvas, which has no viewport to query', () => {
+    // The canvas is a desktop-width iframe simulating a phone, so the media
+    // queries a phone would match never fire there. It asks for one breakpoint
+    // and gets unconditional rules — which is the whole reason the constraint
+    // is emitted through the same generator as everything else.
+    const styles = { 'content-width': { desktop: '1280px', mobile: 'full' } };
+
+    expect(
+      ruleFor(generateThemeCSS(section(styles), 'mobile'), CONTENT_SELECTOR)
+    ).toContain('max-width: none');
+    expect(
+      ruleFor(generateThemeCSS(section(styles), 'desktop'), CONTENT_SELECTOR)
+    ).toContain('max-width: 1280px');
+  });
+});
+
+describe('a section that arranges its children keeps arranging them', () => {
+  it('moves the layout onto the box that now holds the blocks', () => {
+    // On the generic path the wrapper is `display: contents` until a content
+    // width appears, so the blocks are the section's own children for layout
+    // purposes. Turning the wrapper into a real box without this move would
+    // stack a row the designer already had — a break at the exact moment they
+    // first touch the setting.
+    const css = generateThemeCSS(
+      section({
+        'content-width': '1024px',
+        display: 'flex',
+        'justify-content': 'space-between',
+        gap: '24px'
+      })
+    );
+
+    const content = ruleFor(css, CONTENT_SELECTOR);
+    expect(content).toContain('display: flex');
+    expect(content).toContain('justify-content: space-between');
+    expect(content).toContain('gap: 24px');
+    expect(ruleFor(css, BAND_SELECTOR)).not.toContain('display');
+  });
+
+  it('leaves a hidden breakpoint hidden on the band itself', () => {
+    // `display: none` hides the whole band. Moved onto the inner box it would
+    // hide the content and leave the background painting over the gap.
+    const css = generateThemeCSS(
+      section({
+        'content-width': '1024px',
+        display: { desktop: 'grid', mobile: 'none' }
+      })
+    );
+
+    expect(ruleFor(css, BAND_SELECTOR)).toBe('');
+    expect(css).toContain(`${MOBILE_MEDIA_QUERY} {`);
+    expect(css).toContain('display: none');
+    expect(ruleFor(css, CONTENT_SELECTOR)).toContain('display: grid');
+  });
+
+  it('leaves a plain display where it was', () => {
+    const css = generateThemeCSS(
+      section({ 'content-width': '1024px', display: 'block' })
+    );
+
+    expect(ruleFor(css, BAND_SELECTOR)).toContain('display: block');
+  });
+
+  it('moves nothing on a section that renders through its own component', () => {
+    // Those already draw a real box around their children, so the section's
+    // display already applies to it. Moving would change a page that renders
+    // correctly today.
+    const css = generateThemeCSS(
+      section(
+        { 'content-width': '1024px', display: 'flex' },
+        { type: 'stats-counter' }
+      )
+    );
+
+    expect(ruleFor(css, BAND_SELECTOR)).toContain('display: flex');
+    expect(ruleFor(css, CONTENT_SELECTOR)).toContain('max-width: 1024px');
+  });
+});
+
+describe('the setting is additive', () => {
+  it('changes nothing for a section that does not use it', () => {
+    const styles = {
+      'background-color': '#fff',
+      display: 'flex',
+      gap: '16px',
+      'padding-top': '40px'
+    };
+
+    expect(generateThemeCSS(section(styles))).not.toContain(
+      SECTION_CONTENT_ATTRIBUTE
+    );
+    // Returned by reference, so the generator is handed the same object it
+    // always was and produces the same bytes.
+    expect(splitSectionContentWidth(styles).section).toBe(styles);
+  });
+
+  it('leaves the section-level Max Width doing exactly what it did', () => {
+    // Two independent decisions, both honoured: the band held to 80rem and the
+    // content to 1024px inside it. Pages published against the older control
+    // must not move.
+    const css = generateThemeCSS(
+      section({ 'max-width': 'normal', 'content-width': '1024px' })
+    );
+
+    const band = ruleFor(css, BAND_SELECTOR);
+    expect(band).toContain('max-width: 80rem');
+    expect(band).toContain('margin-left: auto');
+    expect(ruleFor(css, CONTENT_SELECTOR)).toContain('max-width: 1024px');
+  });
+
+  it('scopes the rule to a direct child, so a nested band is never caught', () => {
+    expect(generateThemeCSS(section({ 'content-width': '640px' }))).toContain(
+      `> [${SECTION_CONTENT_ATTRIBUTE}]`
+    );
+  });
+});
+
+describe('hasSectionContentWidth', () => {
+  it.each([
+    ['nothing authored', undefined, false],
+    ['an empty selection', { 'content-width': '' }, false],
+    ['a length', { 'content-width': '768px' }, true],
+    ['full width', { 'content-width': 'full' }, true],
+    [
+      'custom with a value',
+      { 'content-width': 'custom', 'content-width-custom': '900px' },
+      true
+    ],
+    ['custom with nothing typed', { 'content-width': 'custom' }, false],
+    ['a phone only', { 'content-width': { mobile: '640px' } }, true]
+  ])('answers %s', (_label, styles, expected) => {
+    expect(hasSectionContentWidth(styles as Record<string, unknown>)).toBe(
+      expected
+    );
+  });
+});

package/src/utils/index.ts

@@ -27,6 +27,10 @@ import {
   isSectionMaxWidthToken,
   resolveSectionMaxWidthValue
 } from './section-max-width';
+import {
+  SECTION_CONTENT_ATTRIBUTE,
+  splitSectionContentWidth
+} from './section-content-width';
 import { hasCustomSectionRenderer } from '../sections/custom-renderer-section-types';
 
 export * from './publish-window';
@@ -35,6 +39,7 @@ export * from './custom-css';
 export * from './breakpoints';
 export * from './checkout-safety';
 export * from './section-max-width';
+export * from './section-content-width';
 
 export type ImageLoadingStrategy = 'eager' | 'lazy';
 export type ImageFetchPriority = 'high' | 'auto' | 'low';
@@ -1426,13 +1431,36 @@ export const generateThemeCSS = (
       const { root: sectionRoot } = splitPartStyles(sectionStyles);
 
       if (Object.keys(sectionRoot).length > 0) {
-        css += generateElementCSS(
-          sectionSelector,
-          hasCustomSectionRenderer(section)
-            ? sectionRoot
-            : resolveSectionMaxWidthTokens(sectionRoot),
-          targetBreakpoint
+        const customRenderer = hasCustomSectionRenderer(section);
+
+        // The content width leaves the band before anything else is decided
+        // about it: it is not a declaration a section ever carries, and on the
+        // generic path it takes the section's child layout with it — see
+        // utils/section-content-width.ts for why that move exists.
+        const { section: band, content } = splitSectionContentWidth(
+          sectionRoot,
+          { moveLayout: !customRenderer }
         );
+
+        if (Object.keys(band).length > 0) {
+          css += generateElementCSS(
+            sectionSelector,
+            customRenderer ? band : resolveSectionMaxWidthTokens(band),
+            targetBreakpoint
+          );
+        }
+
+        // Direct child, so a nested section's wrapper is never caught by an
+        // ancestor's rule. Emitted after the band on purpose: the two address
+        // different elements, but reading the sheet, the band is the thing the
+        // constraint is being carved out of.
+        if (content) {
+          css += generateElementCSS(
+            `${sectionSelector} > [${SECTION_CONTENT_ATTRIBUTE}]`,
+            content as ResponsiveStyles,
+            targetBreakpoint
+          );
+        }
       }
 
       css += generateRootStateCSS(
@@ -1441,11 +1469,7 @@ export const generateThemeCSS = (
         targetBreakpoint
       );
 
-      css += generatePartCSS(
-        sectionSelector,
-        sectionStyles,
-        targetBreakpoint
-      );
+      css += generatePartCSS(sectionSelector, sectionStyles, targetBreakpoint);
     }
 
     if (section.properties) {

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

@@ -0,0 +1,337 @@
+import { BREAKPOINTS, BREAKPOINT_FALLBACKS } from './breakpoints';
+
+/**
+ * How wide the CONTENT of a band is allowed to get, as opposed to how wide the
+ * band is.
+ *
+ * A section already had a `max-width` (Narrow / Normal / None), but that key
+ * lands on the `<section>` itself: constraining it pulls the background colour,
+ * the background image and the border in with the text. What a design almost
+ * always wants is the other split — colour from edge to edge, words held to a
+ * measure and centred — and the only way to express it was to add one of five
+ * prebuilt "container" starters and rebuild the band inside it.
+ *
+ * `content-width` is that split as a setting. It never reaches the section's
+ * own box: it is resolved here into a rule for the wrapper every section
+ * already renders around its blocks (`data-section-content`), so the band stays
+ * full-bleed and only what is inside it is constrained. The section's
+ * horizontal padding keeps working, because the wrapper sits inside the padding
+ * box — which is what stops content touching the screen edge on a phone.
+ *
+ * The value is a real CSS length (`1024px`), not a token: the editor writes the
+ * scale it offers, so there is no vocabulary for the two repos to keep in sync.
+ * Only three spellings mean something here — `full` and `none` for "not
+ * constrained", and `custom`, which defers to the free-length box beside the
+ * select.
+ */
+export const CONTENT_WIDTH_STYLE_KEY = 'content-width';
+export const CONTENT_WIDTH_CUSTOM_STYLE_KEY = 'content-width-custom';
+
+/** camelCase spellings, because published JSON carries both. */
+const CONTENT_WIDTH_KEYS = [CONTENT_WIDTH_STYLE_KEY, 'contentWidth'] as const;
+const CONTENT_WIDTH_CUSTOM_KEYS = [
+  CONTENT_WIDTH_CUSTOM_STYLE_KEY,
+  'contentWidthCustom'
+] as const;
+
+/** The attribute both render paths stamp on the box that holds the blocks. */
+export const SECTION_CONTENT_ATTRIBUTE = 'data-section-content';
+
+/** The option the free-length box is gated on. */
+const CUSTOM = 'custom';
+
+/**
+ * The two spellings of "do not constrain me". `full` is the editor's word and
+ * is not CSS, so it resolves to the one the browser understands — and it has to
+ * resolve to something rather than be dropped, because dropping it would let a
+ * desktop width cascade down to the breakpoint that explicitly opted out.
+ */
+const UNCONSTRAINED = new Set(['full', 'none']);
+
+type Styles = Record<string, unknown>;
+
+const isResponsive = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const read = (styles: Styles, keys: readonly string[]): unknown => {
+  for (const key of keys) {
+    const value = styles[key];
+    if (value !== undefined) return value;
+  }
+  return undefined;
+};
+
+/**
+ * One breakpoint's value out of a responsive entry, following the same chain as
+ * `getResponsiveValue` — a tablet reads the mobile value before the desktop one
+ * — so what this resolves and what the rest of the renderer resolves cannot
+ * disagree.
+ */
+const at = (value: unknown, breakpoint: string): unknown => {
+  if (!isResponsive(value)) return value;
+
+  const own = value[breakpoint];
+  if (own !== undefined) return own;
+
+  for (const next of BREAKPOINT_FALLBACKS[breakpoint] ?? []) {
+    if (value[next] !== undefined) return value[next];
+  }
+
+  return value.desktop;
+};
+
+/**
+ * The `max-width` one breakpoint should carry, or `''` for "nothing authored
+ * here" — which is not the same as "unconstrained": an unauthored breakpoint
+ * inherits, an explicitly full one overrides.
+ *
+ * A `custom` selection with an empty box is treated as unauthored rather than
+ * as full width, so a half-typed value behaves like the setting not being there
+ * yet instead of silently widening the band.
+ */
+export const resolveContentWidthValue = (
+  choice: unknown,
+  customValue: unknown
+): string => {
+  if (choice === undefined || choice === null || choice === '') return '';
+
+  const normalized = String(choice).trim();
+  if (!normalized) return '';
+  if (UNCONSTRAINED.has(normalized.toLowerCase())) return 'none';
+
+  if (normalized.toLowerCase() === CUSTOM) {
+    const custom =
+      customValue === undefined || customValue === null
+        ? ''
+        : String(customValue).trim();
+    return custom;
+  }
+
+  return normalized;
+};
+
+/** Whether this section constrains its content at any breakpoint. */
+export const hasSectionContentWidth = (
+  styles: Styles | undefined | null
+): boolean => {
+  if (!styles) return false;
+
+  const choice = read(styles, CONTENT_WIDTH_KEYS);
+  const custom = read(styles, CONTENT_WIDTH_CUSTOM_KEYS);
+  if (choice === undefined) return false;
+
+  if (!isResponsive(choice)) {
+    return resolveContentWidthValue(choice, at(custom, 'desktop')) !== '';
+  }
+
+  return BREAKPOINTS.some(
+    (breakpoint) =>
+      choice[breakpoint] !== undefined &&
+      resolveContentWidthValue(choice[breakpoint], at(custom, breakpoint)) !==
+        ''
+  );
+};
+
+/**
+ * Declarations that arrange a section's CHILDREN rather than draw the section.
+ *
+ * They matter here because of what the wrapper is: on the generic path it is
+ * `display: contents` today, so a section set to Flex lays its blocks out
+ * directly. Turning that wrapper into a real box to constrain it would make the
+ * blocks stack — the row a designer already had would break the moment they
+ * touched the new setting. Moving these onto the wrapper keeps the arrangement
+ * and changes only where it is declared; the section is left a plain block,
+ * which is what a `<section>` is anyway.
+ *
+ * The list is the arranging half of the box model only. Padding, background,
+ * border and position stay on the band, which is the entire point of the
+ * setting.
+ */
+const CHILD_LAYOUT_KEYS = new Set([
+  'flex-direction',
+  'flex-wrap',
+  'flex-flow',
+  'justify-content',
+  'justify-items',
+  'align-items',
+  'align-content',
+  'place-items',
+  'place-content',
+  'gap',
+  'row-gap',
+  'column-gap',
+  'grid-template-columns',
+  'grid-template-rows',
+  'grid-template-areas',
+  'grid-auto-flow',
+  'grid-auto-columns',
+  'grid-auto-rows'
+]);
+
+/** The `display` values that make an element arrange its children. */
+const CHILD_LAYOUT_DISPLAYS = new Set([
+  'flex',
+  'inline-flex',
+  'grid',
+  'inline-grid'
+]);
+
+const kebab = (key: string): string =>
+  key.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+
+/**
+ * Splits `display` between the band and the wrapper, breakpoint by breakpoint.
+ *
+ * Only the arranging values move. `none` in particular must stay behind: it
+ * hides the whole band, and moving it would leave the background painting over
+ * a breakpoint the designer switched off.
+ */
+const splitDisplay = (
+  value: unknown
+): { section?: unknown; content?: unknown } => {
+  const moves = (candidate: unknown): boolean =>
+    typeof candidate === 'string' &&
+    CHILD_LAYOUT_DISPLAYS.has(candidate.trim().toLowerCase());
+
+  if (!isResponsive(value)) {
+    return moves(value) ? { content: value } : { section: value };
+  }
+
+  const section: Record<string, unknown> = {};
+  const content: Record<string, unknown> = {};
+
+  Object.entries(value).forEach(([breakpoint, breakpointValue]) => {
+    if (moves(breakpointValue)) content[breakpoint] = breakpointValue;
+    else section[breakpoint] = breakpointValue;
+  });
+
+  return {
+    section: Object.keys(section).length > 0 ? section : undefined,
+    content: Object.keys(content).length > 0 ? content : undefined
+  };
+};
+
+/**
+ * The `max-width` entry the wrapper should carry, in whichever shape the
+ * authored value was in — a scalar stays a scalar, so a section constrained at
+ * every width emits one rule rather than three.
+ */
+const buildMaxWidth = (styles: Styles): string | Record<string, string> => {
+  const choice = read(styles, CONTENT_WIDTH_KEYS);
+  const custom = read(styles, CONTENT_WIDTH_CUSTOM_KEYS);
+
+  if (!isResponsive(choice)) {
+    return resolveContentWidthValue(choice, at(custom, 'desktop'));
+  }
+
+  const entries: Array<[string, string]> = [];
+
+  BREAKPOINTS.forEach((breakpoint) => {
+    if (choice[breakpoint] === undefined) return;
+
+    const resolved = resolveContentWidthValue(
+      choice[breakpoint],
+      at(custom, breakpoint)
+    );
+
+    if (resolved !== '') entries.push([breakpoint, resolved]);
+  });
+
+  return Object.fromEntries(entries);
+};
+
+export interface SectionContentWidthSplit {
+  /** What the band itself still declares — always returned, never null. */
+  section: Styles;
+  /** The wrapper's own rule, or null when this section constrains nothing. */
+  content: Styles | null;
+}
+
+/**
+ * Takes a section root's styles apart into the band and the box inside it.
+ *
+ * `moveLayout` is false for a section that renders through its own component:
+ * those already draw a real box around their children, so the section's
+ * `display` already applies to that box and moving it would change a page that
+ * renders correctly today.
+ *
+ * A section with no content width authored gets its styles back by reference,
+ * so every composition that renders today produces byte-identical CSS.
+ */
+export const splitSectionContentWidth = (
+  styles: Styles,
+  options: { moveLayout?: boolean } = {}
+): SectionContentWidthSplit => {
+  const maxWidth = hasSectionContentWidth(styles) ? buildMaxWidth(styles) : '';
+  const constrained =
+    typeof maxWidth === 'string'
+      ? maxWidth !== ''
+      : Object.keys(maxWidth).length > 0;
+
+  const carriesHelperKey = Object.keys(styles).some((key) => {
+    const normalized = kebab(key);
+    return (
+      normalized === CONTENT_WIDTH_STYLE_KEY ||
+      normalized === CONTENT_WIDTH_CUSTOM_STYLE_KEY
+    );
+  });
+
+  if (!constrained && !carriesHelperKey) {
+    return { section: styles, content: null };
+  }
+
+  const section: Styles = {};
+  const moved: Styles = {};
+
+  Object.entries(styles).forEach(([key, value]) => {
+    const normalized = kebab(key);
+
+    // Neither is a CSS property. Emitted as-is they would be a declaration the
+    // browser throws away, which is exactly the failure the old `max-width`
+    // token had on the default render path.
+    if (
+      normalized === CONTENT_WIDTH_STYLE_KEY ||
+      normalized === CONTENT_WIDTH_CUSTOM_STYLE_KEY
+    ) {
+      return;
+    }
+
+    if (!constrained || !options.moveLayout) {
+      section[key] = value;
+      return;
+    }
+
+    if (normalized === 'display') {
+      const split = splitDisplay(value);
+      if (split.section !== undefined) section[key] = split.section;
+      if (split.content !== undefined) moved[normalized] = split.content;
+      return;
+    }
+
+    if (CHILD_LAYOUT_KEYS.has(normalized)) {
+      moved[normalized] = value;
+      return;
+    }
+
+    section[key] = value;
+  });
+
+  if (!constrained) return { section, content: null };
+
+  return {
+    section,
+    // `width` first, and always: a wrapper that is a flex item — which is what
+    // it becomes inside a section that arranges its children — would otherwise
+    // shrink to its content and never reach the width it is being capped at.
+    // Auto margins are what centre it; they are inert wherever the width is
+    // unconstrained, so a desktop-only constraint still leaves a phone
+    // full-bleed.
+    content: {
+      width: '100%',
+      'max-width': maxWidth,
+      'margin-left': 'auto',
+      'margin-right': 'auto',
+      ...moved
+    }
+  };
+};