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

package/CHANGELOG.md

@@ -1,36 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.53-rc.0
-
-### Patch Changes
-
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea0688]
-- Updated dependencies
-- Updated dependencies [2fea4143]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08f]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f4]
-- Updated dependencies [57d7eb30]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a71]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d0]
-- Updated dependencies [4ac7b2a1]
-- Updated dependencies [e9598c71]
-- Updated dependencies [4998a963]
-- Updated dependencies [804d2bd6]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a63]
-- Updated dependencies [e18836b2]
-  - @akinon/next@2.0.53-rc.0
-  - @akinon/theme-contract@2.0.53-rc.0
+## 2.0.53
+
+### Patch Changes
+
+- a406d24: ZERO-4748: Translate section max-width tokens into CSS lengths for default-rendered sections, and centre the section a token constrains unless the composition already sets a horizontal margin
+  - @akinon/next@2.0.53
+  - @akinon/theme-contract@2.0.53
 
 ## 2.0.52
 

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.53-rc.0",
+  "version": "2.0.53",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.53-rc.0",
+    "@akinon/next": "2.0.53",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.53-rc.0",
+    "@akinon/theme-contract": "2.0.53",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.53-rc.0",
+    "@akinon/next": "2.0.53",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/sections/__tests__/custom-renderer-section-types.test.ts

@@ -0,0 +1,70 @@
+import sectionRendererRegistry from '../section-renderer-registry';
+import {
+  CUSTOM_RENDERER_SECTION_TYPES,
+  hasCustomSectionRenderer
+} from '../custom-renderer-section-types';
+import type { Section } from '../../theme-section';
+
+const section = (over: Partial<Section> = {}): Section =>
+  ({
+    id: 's1',
+    type: 'custom',
+    name: 'S',
+    label: 'S',
+    order: 0,
+    hidden: false,
+    properties: {},
+    styles: {},
+    blocks: [],
+    ...over
+  } as unknown as Section);
+
+/**
+ * The CSS generator cannot import the registry without closing a module cycle,
+ * so it reads a plain copy of the registered types. This is the lock that keeps
+ * the copy true: registering a renderer without listing it here would hand that
+ * section's outer element a max-width its own component already applies.
+ */
+describe('the custom-renderer type list matches the registry', () => {
+  it('lists exactly the registered types', () => {
+    expect([...CUSTOM_RENDERER_SECTION_TYPES].sort()).toEqual(
+      sectionRendererRegistry.registeredTypes().sort()
+    );
+  });
+
+  it('agrees with the registry section by section', () => {
+    CUSTOM_RENDERER_SECTION_TYPES.forEach((type) => {
+      expect(sectionRendererRegistry.hasCustomRenderer(type)).toBe(true);
+    });
+  });
+});
+
+describe('hasCustomSectionRenderer', () => {
+  it('is false for the types the generic block loop renders', () => {
+    ['custom', 'default', 'hero', 'newsletter-signup-banner'].forEach(
+      (type) => {
+        expect(hasCustomSectionRenderer(section({ type }))).toBe(false);
+      }
+    );
+  });
+
+  it('is true for a registered type', () => {
+    expect(hasCustomSectionRenderer(section({ type: 'stats-counter' }))).toBe(
+      true
+    );
+  });
+
+  it('follows the tab hatch, which overrides the section type', () => {
+    // theme-section hands any section holding `tab` blocks to TabsSection
+    // whatever its own type says, so it owns its container like a registered
+    // type does.
+    expect(
+      hasCustomSectionRenderer(
+        section({
+          type: 'custom',
+          blocks: [{ id: 'b1', type: 'tab' }] as unknown as Section['blocks']
+        })
+      )
+    ).toBe(true);
+  });
+});

package/src/sections/custom-renderer-section-types.ts

@@ -0,0 +1,51 @@
+/**
+ * The section types that render through their own component instead of the
+ * generic block loop, as plain data.
+ *
+ * The registry itself cannot answer this question for the CSS generator: the
+ * generator is a leaf module that every section component imports, so importing
+ * the registry back into it closes a cycle in which the registry evaluates
+ * before the components it registers and silently stores `undefined` for them.
+ * The list is duplicated here on purpose and pinned to the registry by
+ * `__tests__/custom-renderer-section-types.test.ts`, which fails the moment a
+ * renderer is registered or removed without this file following.
+ */
+export const CUSTOM_RENDERER_SECTION_TYPES: readonly string[] = [
+  'before-after',
+  'contact-form',
+  'countdown-banner',
+  'coupon-banner',
+  'divider',
+  'featured-product-spotlight',
+  'find-in-store',
+  'flash-deals-slider',
+  'hover-showcase',
+  'image-hotspot',
+  'installment-options',
+  'notification-banner',
+  'order-tracking-lookup',
+  'posts-slider',
+  'pre-order-launch-banner',
+  'shipping-threshold-progress',
+  'stats-counter',
+  'tabs'
+];
+
+/**
+ * Mirrors how `theme-section` picks a renderer, including the tab hatch: a
+ * section holding `tab` blocks is rendered by `TabsSection` whatever its own
+ * type says, so it owns its layout container the same way a registered type
+ * does.
+ *
+ * Typed by shape rather than against `Section`, because the CSS generator
+ * carries its own structural copy of that interface and the two are not
+ * assignable to one another.
+ */
+export const hasCustomSectionRenderer = (section: {
+  type?: string;
+  blocks?: { type?: string }[];
+}): boolean => {
+  if (section.blocks?.some((block) => block.type === 'tab')) return true;
+
+  return CUSTOM_RENDERER_SECTION_TYPES.includes(section.type ?? '');
+};

package/src/sections/section-renderer-registry.tsx

@@ -42,6 +42,10 @@ class SectionRendererRegistry {
   hasCustomRenderer(type: string): boolean {
     return this.renderers.has(type);
   }
+
+  registeredTypes(): string[] {
+    return [...this.renderers.keys()];
+  }
 }
 
 const sectionRendererRegistry = new SectionRendererRegistry();

package/src/sections/stats-counter-section.tsx

@@ -7,7 +7,11 @@ import { twMerge } from 'tailwind-merge';
 import ThemeBlock, { Block } from '../theme-block';
 import { Section } from '../theme-section';
 import { useThemeSettingsContext } from '../theme-settings-context';
-import { getCSSStyles, getResponsiveValue } from '../utils';
+import {
+  getCSSStyles,
+  getResponsiveValue,
+  getSectionMaxWidthClass
+} from '../utils';
 
 import { postToEditor } from '../editor-bridge';
 import { PreviewToEditorMessageType } from '@akinon/theme-contract';
@@ -446,12 +450,7 @@ const StatsCounterSection: React.FC<StatsCounterSectionProps> = ({
     currentBreakpoint,
     'normal'
   );
-  const maxWidthClass =
-    maxWidth === 'narrow'
-      ? 'max-w-4xl'
-      : maxWidth === 'normal'
-      ? 'max-w-7xl'
-      : '';
+  const maxWidthClass = getSectionMaxWidthClass(maxWidth);
   const hasMaxWidth = maxWidth !== 'none' && maxWidth !== 'full';
 
   const filteredStyles = Object.fromEntries(

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

@@ -0,0 +1,283 @@
+import { generateThemeCSS } from '../index';
+import { SECTION_MAX_WIDTH_SCALE } from '../section-max-width';
+import type { Section } from '../../theme-section';
+
+/**
+ * `max-width` is offered on a section as Narrow / Normal / Full / None, and
+ * those tokens used to reach the stylesheet verbatim: `max-width: narrow` is a
+ * declaration the browser drops, so the control did nothing on every section
+ * the generic block loop renders — `custom`, `hero`, `newsletter-signup-banner`.
+ */
+
+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
+];
+
+describe('section max-width tokens reach CSS as lengths', () => {
+  it('translates narrow', () => {
+    const css = generateThemeCSS(section({ 'max-width': 'narrow' }));
+
+    expect(css).toContain('max-width: 56rem');
+    expect(css).not.toContain('max-width: narrow');
+  });
+
+  it('translates normal', () => {
+    const css = generateThemeCSS(section({ 'max-width': 'normal' }));
+
+    expect(css).toContain('max-width: 80rem');
+    expect(css).not.toContain('max-width: normal');
+  });
+
+  it('translates the camelCase spelling of the key too', () => {
+    const css = generateThemeCSS(section({ maxWidth: 'narrow' }));
+
+    expect(css).toContain('max-width: 56rem');
+  });
+
+  it('resolves `full` to the only real CSS spelling of "no constraint"', () => {
+    const css = generateThemeCSS(section({ 'max-width': 'full' }));
+
+    expect(css).toContain('max-width: none');
+    expect(css).not.toContain('max-width: full');
+  });
+
+  it('leaves `none` alone — it is already real CSS', () => {
+    expect(generateThemeCSS(section({ 'max-width': 'none' }))).toContain(
+      'max-width: none'
+    );
+  });
+
+  it('translates per breakpoint, inside the media query', () => {
+    const css = generateThemeCSS(
+      section({ 'max-width': { desktop: 'narrow', mobile: 'none' } })
+    );
+
+    expect(css).toContain('max-width: 56rem');
+    expect(css).toContain('max-width: none');
+    expect(css).not.toContain('max-width: narrow');
+  });
+
+  it('translates for the breakpoint the designer canvas is showing', () => {
+    const css = generateThemeCSS(
+      section({ 'max-width': { desktop: 'none', mobile: 'normal' } }),
+      'mobile'
+    );
+
+    expect(css).toContain('max-width: 80rem');
+  });
+});
+
+describe('only the known tokens are translated', () => {
+  it.each(['640px', '75%', '48rem', 'calc(100% - 2rem)', 'var(--shell)'])(
+    'passes the real CSS value %s through untouched',
+    (value) => {
+      expect(generateThemeCSS(section({ 'max-width': value }))).toContain(
+        `max-width: ${value}`
+      );
+    }
+  );
+
+  it('passes an unrecognized word through rather than guessing', () => {
+    expect(generateThemeCSS(section({ 'max-width': 'wide' }))).toContain(
+      'max-width: wide'
+    );
+  });
+
+  it('touches no other property that happens to carry a token word', () => {
+    const css = generateThemeCSS(
+      section({ width: 'narrow', 'min-width': 'normal' })
+    );
+
+    expect(css).toContain('width: narrow');
+    expect(css).toContain('min-width: normal');
+  });
+});
+
+describe('a custom-renderer section keeps resolving its own max-width', () => {
+  // Its component applies the token to the container it owns. Putting the
+  // length on the outer <section> as well would pull that element in from
+  // full-bleed and shrink the inner container by the section padding.
+  it('leaves the token on the section root untranslated', () => {
+    const css = generateThemeCSS(
+      section({ 'max-width': 'narrow' }, { type: 'stats-counter' })
+    );
+
+    expect(css).toContain('max-width: narrow');
+    expect(css).not.toContain('max-width: 56rem');
+  });
+
+  it('leaves it alone for a section reached through the tab hatch', () => {
+    const css = generateThemeCSS(
+      section(
+        { 'max-width': 'narrow' },
+        {
+          type: 'custom',
+          blocks: [{ id: 'b1', type: 'tab' }] as unknown as Section['blocks']
+        }
+      )
+    );
+
+    expect(css).toContain('max-width: narrow');
+  });
+});
+
+describe('the scale is one table, not two', () => {
+  // The class and the length are the same measurement: Tailwind's max-w-4xl is
+  // 56rem and max-w-7xl is 80rem. A test would not catch them drifting if they
+  // were declared in two places, which is why they are declared in one.
+  it('pairs each Tailwind class with the length that class means', () => {
+    expect(SECTION_MAX_WIDTH_SCALE).toEqual({
+      narrow: { className: 'max-w-4xl', length: '56rem' },
+      normal: { className: 'max-w-7xl', length: '80rem' }
+    });
+  });
+});
+
+/**
+ * A constrained width and `mx-auto` are one decision everywhere else in the
+ * product — every custom-renderer section pairs them — so the default path
+ * producing a left-aligned constrained column reads as a bug the first time a
+ * designer uses the control.
+ */
+describe('a resolved token also centres the section', () => {
+  it('centres a narrow section', () => {
+    const css = generateThemeCSS(section({ 'max-width': 'narrow' }));
+
+    expect(css).toContain('max-width: 56rem');
+    expect(css).toContain('margin-left: auto');
+    expect(css).toContain('margin-right: auto');
+  });
+
+  it('centres a normal section', () => {
+    const css = generateThemeCSS(section({ 'max-width': 'normal' }));
+
+    expect(css).toContain('margin-left: auto');
+    expect(css).toContain('margin-right: auto');
+  });
+
+  it('centres the camelCase spelling of the key too', () => {
+    expect(generateThemeCSS(section({ maxWidth: 'narrow' }))).toContain(
+      'margin-left: auto'
+    );
+  });
+
+  it('centres when only one breakpoint is constrained', () => {
+    // The auto margin is inert wherever the width is unconstrained, so mobile
+    // stays full-bleed without needing a rule of its own.
+    const css = generateThemeCSS(
+      section({ 'max-width': { desktop: 'narrow', mobile: 'none' } })
+    );
+
+    expect(css).toContain('margin-left: auto');
+  });
+
+  it.each(['none', 'full'])(
+    'does not centre %s — it is not held to a width',
+    (value) => {
+      const css = generateThemeCSS(section({ 'max-width': value }));
+
+      expect(css).not.toContain('margin-left: auto');
+      expect(css).not.toContain('margin-right: auto');
+    }
+  );
+
+  it('does not centre a real CSS length it did not resolve', () => {
+    // Only a token is ours to interpret; a length the author typed carries no
+    // instruction about where the section sits.
+    const css = generateThemeCSS(section({ 'max-width': '640px' }));
+
+    expect(css).toContain('max-width: 640px');
+    expect(css).not.toContain('margin-left: auto');
+  });
+
+  it('leaves a custom-renderer section uncentred here', () => {
+    // Its own component pairs the token with mx-auto on the container it owns.
+    const css = generateThemeCSS(
+      section({ 'max-width': 'narrow' }, { type: 'stats-counter' })
+    );
+
+    expect(css).not.toContain('margin-left: auto');
+  });
+});
+
+describe('an authored horizontal margin wins over centring', () => {
+  it.each([
+    ['margin-left', '0px'],
+    ['margin-right', '0px'],
+    ['marginLeft', '24px'],
+    ['margin', '0 0 0 40px'],
+    ['margin-inline', '0']
+  ])('keeps the author %s', (key, value) => {
+    const css = generateThemeCSS(
+      section({ 'max-width': 'narrow', [key]: value })
+    );
+
+    expect(css).toContain('max-width: 56rem');
+    expect(css).not.toContain('margin-left: auto');
+    expect(css).not.toContain('margin-right: auto');
+  });
+
+  it('keeps an authored margin written per breakpoint', () => {
+    const css = generateThemeCSS(
+      section({
+        'max-width': 'narrow',
+        'margin-left': { desktop: '80px' }
+      })
+    );
+
+    expect(css).toContain('margin-left: 80px');
+    expect(css).not.toContain('margin-left: auto');
+  });
+
+  it('still centres when a vertical margin is the only one authored', () => {
+    const css = generateThemeCSS(
+      section({ 'max-width': 'narrow', 'margin-top': '40px' })
+    );
+
+    expect(css).toContain('margin-top: 40px');
+    expect(css).toContain('margin-left: auto');
+  });
+
+  it('centres past a horizontal margin key carrying no value', () => {
+    // The generator drops an empty value before it reaches CSS, so it is not
+    // the author having decided anything.
+    const css = generateThemeCSS(
+      section({ 'max-width': 'narrow', 'margin-left': '' })
+    );
+
+    expect(css).toContain('margin-left: auto');
+  });
+});
+
+describe('untouched styles are returned by reference', () => {
+  it('emits byte-identical CSS for a section with no max-width', () => {
+    const styles = { 'padding-top': '40px', 'background-color': '#fff' };
+
+    expect(generateThemeCSS(section(styles))).toBe(
+      generateThemeCSS(section(styles))
+    );
+  });
+
+  it('adds no margin to a section with no max-width', () => {
+    const css = generateThemeCSS(
+      section({ 'padding-top': '40px', 'background-color': '#fff' })
+    );
+
+    expect(css).not.toContain('margin-left');
+    expect(css).not.toContain('margin-right');
+  });
+});

package/src/utils/index.ts

@@ -19,12 +19,18 @@ import {
   MOBILE_MEDIA_QUERY,
   TABLET_MEDIA_QUERY
 } from './breakpoints';
+import {
+  isSectionMaxWidthToken,
+  resolveSectionMaxWidthValue
+} from './section-max-width';
+import { hasCustomSectionRenderer } from '../sections/custom-renderer-section-types';
 
 export * from './publish-window';
 export * from './part-styles';
 export * from './custom-css';
 export * from './breakpoints';
 export * from './checkout-safety';
+export * from './section-max-width';
 
 export type ImageLoadingStrategy = 'eager' | 'lazy';
 export type ImageFetchPriority = 'high' | 'auto' | 'low';
@@ -349,6 +355,126 @@ const stripBoundStyleValues = <T extends Record<string, unknown>>(
   return changed ? (stripped as T) : styles;
 };
 
+/**
+ * The ways a composition can already have placed the section horizontally, in
+ * both spellings the generator accepts. The `margin` shorthand is included
+ * because it sets the horizontal pair too.
+ */
+const HORIZONTAL_MARGIN_KEYS = new Set([
+  'margin',
+  'margin-left',
+  'margin-right',
+  'margin-inline',
+  'margin-inline-start',
+  'margin-inline-end'
+]);
+
+/**
+ * Whether the author positioned the section themselves. An empty value is not
+ * an answer — the generator drops those before they reach CSS — so only a real
+ * value counts as the author having decided where the section sits.
+ */
+const authorsHorizontalMargin = (styles: Record<string, unknown>): boolean =>
+  Object.entries(styles).some(([key, value]) => {
+    if (!HORIZONTAL_MARGIN_KEYS.has(camelToKebab(key))) return false;
+
+    const isSet = (candidate: unknown): boolean =>
+      candidate !== undefined && candidate !== null && candidate !== '';
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      return Object.values(value as Record<string, unknown>).some(isSet);
+    }
+
+    return isSet(value);
+  });
+
+/**
+ * `max-width` is the one section style the editor writes as a token rather than
+ * a CSS value, so it is the one that has to be translated before emission —
+ * `max-width: narrow` is a declaration the browser throws away, which is why
+ * the control appeared to do nothing on every section that renders through the
+ * default path.
+ *
+ * Resolving the token also centres the section, because a constrained width and
+ * `mx-auto` are one decision everywhere else in the product — every
+ * custom-renderer section pairs them. An authored horizontal margin wins: the
+ * designer who set one has already said where the section sits.
+ *
+ * Only the section root is rewritten, and only for sections the generic block
+ * loop renders. A custom-renderer section resolves the same token itself, onto
+ * the container it owns; giving its outer `<section>` the length as well would
+ * pull that element in from full-bleed and narrow the inner container by the
+ * section padding, changing pages that render correctly today.
+ *
+ * Styles with no token are returned by reference, so every composition that
+ * renders today produces byte-identical CSS.
+ */
+const resolveSectionMaxWidthTokens = <T extends Record<string, unknown>>(
+  styles: T
+): T => {
+  let changed = false;
+  // `full` and `none` resolve too, but they mean "no constraint" and must not
+  // centre anything — only a width the section is actually held to.
+  let constrained = false;
+  const resolved: Record<string, unknown> = {};
+
+  Object.entries(styles).forEach(([key, value]) => {
+    if (key !== 'max-width' && key !== 'maxWidth') {
+      resolved[key] = value;
+      return;
+    }
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      const rawEntries = Object.entries(value as Record<string, unknown>);
+
+      if (rawEntries.some(([, breakpointValue]) =>
+        isSectionMaxWidthToken(breakpointValue)
+      )) {
+        constrained = true;
+      }
+
+      const entries = rawEntries.map(
+        ([breakpoint, breakpointValue]) =>
+          [breakpoint, resolveSectionMaxWidthValue(breakpointValue)] as const
+      );
+
+      if (
+        entries.some(
+          ([breakpoint, breakpointValue]) =>
+            breakpointValue !== (value as Record<string, unknown>)[breakpoint]
+        )
+      ) {
+        changed = true;
+        resolved[key] = Object.fromEntries(entries);
+        return;
+      }
+
+      resolved[key] = value;
+      return;
+    }
+
+    if (isSectionMaxWidthToken(value)) constrained = true;
+
+    const resolvedValue = resolveSectionMaxWidthValue(value);
+    if (resolvedValue !== value) changed = true;
+    resolved[key] = resolvedValue;
+  });
+
+  // A constrained section that is not centred reads as a bug the first time a
+  // designer uses the control: every custom-renderer section pairs the same
+  // token with `mx-auto`, so a left-aligned column is not what the control is
+  // understood to mean. Emitted as auto margins rather than per breakpoint
+  // because an auto margin is inert wherever the width is unconstrained — a
+  // token on desktop only still leaves mobile full-bleed.
+  if (constrained && !authorsHorizontalMargin(styles)) {
+    resolved['margin-left'] = 'auto';
+    resolved['margin-right'] = 'auto';
+    changed = true;
+  }
+
+  return changed ? (resolved as T) : styles;
+};
+
 export const getCSSStyles = (
   rawStyles?: Record<string, unknown>,
   themeSettings?: ThemeSettings,
@@ -1260,7 +1386,9 @@ export const generateThemeCSS = (
       if (Object.keys(sectionRoot).length > 0) {
         css += generateElementCSS(
           sectionSelector,
-          sectionRoot,
+          hasCustomSectionRenderer(section)
+            ? sectionRoot
+            : resolveSectionMaxWidthTokens(sectionRoot),
           targetBreakpoint
         );
       }

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

@@ -0,0 +1,49 @@
+/**
+ * A section's `max-width` is authored as a token, not a length: the editor's
+ * section configs offer Narrow / Normal / Full / None. Every custom-renderer
+ * section translated those tokens itself, each carrying its own inline copy of
+ * the same two values, while sections that render through the default path had
+ * no translation anywhere — the token reached the generated stylesheet
+ * verbatim and the browser dropped the declaration, so the control did nothing.
+ *
+ * The scale lives here once, in both forms its two consumers need: a Tailwind
+ * class for the section components that compose one, and a CSS length for the
+ * stylesheet generator, which has no classes to compose. The two columns are
+ * the same measurement — `max-w-4xl` is 56rem and `max-w-7xl` is 80rem — and
+ * holding them in one table is what keeps them from drifting apart.
+ */
+export const SECTION_MAX_WIDTH_SCALE = {
+  narrow: { className: 'max-w-4xl', length: '56rem' },
+  normal: { className: 'max-w-7xl', length: '80rem' }
+} as const;
+
+export type SectionMaxWidthToken = keyof typeof SECTION_MAX_WIDTH_SCALE;
+
+export const isSectionMaxWidthToken = (
+  value: unknown
+): value is SectionMaxWidthToken =>
+  typeof value === 'string' &&
+  Object.prototype.hasOwnProperty.call(SECTION_MAX_WIDTH_SCALE, value);
+
+/**
+ * The Tailwind class a constrained token maps to. `full`, `none`, a real CSS
+ * length and anything unrecognized all produce no class: they either mean "no
+ * constraint" or they are a value only the stylesheet can express.
+ */
+export const getSectionMaxWidthClass = (value: unknown): string =>
+  isSectionMaxWidthToken(value) ? SECTION_MAX_WIDTH_SCALE[value].className : '';
+
+/**
+ * The CSS value a section `max-width` should actually carry. `full` and `none`
+ * both mean "no constraint" in the editor's vocabulary but only `none` is real
+ * CSS, so `full` resolves to it rather than staying a dropped declaration.
+ * Everything else — `640px`, a `calc()`, a custom property — is returned
+ * untouched, because only the known tokens are ours to translate.
+ */
+export const resolveSectionMaxWidthValue = (value: unknown): unknown => {
+  if (isSectionMaxWidthToken(value)) {
+    return SECTION_MAX_WIDTH_SCALE[value].length;
+  }
+
+  return value === 'full' ? 'none' : value;
+};