@astryxdesign/core 0.4.4 → 0.4.5-canary.1fdecb1

package/src/Item/Item.tsx

@@ -106,6 +106,15 @@ export interface ItemProps extends BaseProps<HTMLElement> {
    */
   descriptionLines?: number;
 
+  /**
+   * How the label and description sit together. `stacked` puts the description
+   * on its own line below the label; `inline` keeps both on one line, with the
+   * description ellipsizing first, so the row fits a fixed-height host.
+   *
+   * @default 'stacked'
+   */
+  layout?: 'stacked' | 'inline';
+
   /**
    * Click handler. Makes the item clickable with button semantics.
    */
@@ -264,6 +273,25 @@ const styles = stylex.create({
     minWidth: 0,
     textAlign: 'start',
   },
+  // `layout="inline"`: label and description share one line, so the row fits a
+  // fixed-height host such as a Selector trigger inside an InputGroup.
+  inlineContent: {
+    flexDirection: 'row',
+    // Centered, not baseline-aligned: two different font sizes on a shared
+    // baseline make a line box taller than either line, which would push a
+    // fixed-height host (a Selector trigger) a pixel off its size token.
+    alignItems: 'center',
+    columnGap: spacingVars['--spacing-1'],
+  },
+  inlineLabel: {
+    flexShrink: 0,
+  },
+  // The description yields width first, so the label — the part that identifies
+  // the item — is the last thing to ellipsize.
+  inlineDescription: {
+    flexShrink: 1,
+    minWidth: 0,
+  },
   label: {
     // Falls back to the primary text token; a parent (e.g. a destructive menu
     // item) can recolor the label by setting --_item-label-color.
@@ -358,6 +386,7 @@ export function Item({
   density = 'balanced',
   labelLines,
   descriptionLines,
+  layout = 'stacked',
   onClick,
   interactiveRef,
   href,
@@ -420,12 +449,16 @@ export function Item({
         ? styles.labelSingleTruncate
         : null;
 
+  // Inline rows are one line by definition, so the description always
+  // ellipsizes there — a ReactNode description cannot wrap the row open.
+  const isInline = layout === 'inline' && description != null;
+
   const descriptionTruncateStyle =
     descriptionLines != null
       ? descriptionLines === 1
         ? styles.descriptionSingleTruncate
         : styles.descriptionMultiTruncate
-      : isStringDescription
+      : isStringDescription || isInline
         ? styles.descriptionSingleTruncate
         : null;
 
@@ -434,6 +467,7 @@ export function Item({
       <span
         {...stylex.props(
           styles.label,
+          isInline && styles.inlineLabel,
           labelTruncateStyle,
           labelLines != null &&
             labelLines > 1 &&
@@ -445,6 +479,7 @@ export function Item({
         <span
           {...stylex.props(
             styles.description,
+            isInline && styles.inlineDescription,
             descriptionTruncateStyle,
             descriptionLines != null &&
               descriptionLines > 1 &&
@@ -481,6 +516,7 @@ export function Item({
         <span
           {...stylex.props(
             styles.content,
+            isInline && styles.inlineContent,
             isDisabled && styles.disabledContent,
           )}>
           {labelAndDescription}
@@ -494,6 +530,7 @@ export function Item({
           tabIndex={isDisabled ? -1 : undefined}
           {...stylex.props(
             styles.invisibleAnchor,
+            isInline && styles.inlineContent,
             isDisabled && styles.disabledContent,
           )}>
           {labelAndDescription}
@@ -505,6 +542,7 @@ export function Item({
           disabled={isDisabled}
           {...stylex.props(
             styles.invisibleButton,
+            isInline && styles.inlineContent,
             isDisabled && styles.disabledContent,
           )}>
           {labelAndDescription}
@@ -513,6 +551,7 @@ export function Item({
         <span
           {...stylex.props(
             styles.content,
+            isInline && styles.inlineContent,
             isDisabled && styles.disabledContent,
           )}>
           {labelAndDescription}

package/src/Layer/useLayer.tsx

@@ -29,6 +29,7 @@ import {createPortal} from 'react-dom';
 import {addAnchorName, removeAnchorName} from './anchorName';
 import {resolveLayerPortalTarget} from './layerHost';
 import {typeScaleVars, typographyVars} from '../theme/tokens.stylex';
+import {overlayPaddingReset} from '../Layout/padding.stylex';
 
 const styles = stylex.create({
   // Base reset for all layers
@@ -771,7 +772,12 @@ export function useLayer(
             : styles.offsetInline(toCssLength(offset))
           : null;
 
-      const stylexResult = stylex.props(styles.base, offsetStyle, xstyle);
+      const stylexResult = stylex.props(
+        styles.base,
+        overlayPaddingReset.reset,
+        offsetStyle,
+        xstyle,
+      );
       const combinedClassName = extraClassName
         ? `${extraClassName} ${stylexResult.className ?? ''}`
         : stylexResult.className;
@@ -835,7 +841,12 @@ export function useLayer(
         left: x,
       };
 
-      const stylexResult = stylex.props(styles.base, styles.fixed, xstyle);
+      const stylexResult = stylex.props(
+        styles.base,
+        overlayPaddingReset.reset,
+        styles.fixed,
+        xstyle,
+      );
       const combinedClassName = extraClassName
         ? `${extraClassName} ${stylexResult.className ?? ''}`
         : stylexResult.className;

package/src/Layout/Layout.doc.mjs

@@ -93,6 +93,24 @@ export const docs = {
       description: 'Height behavior: fill the container or grow with content.',
       default: "'fill'",
     },
+    {
+      name: 'contentWidth',
+      type: 'number | string',
+      description:
+        'Maximum width of the content within each slot (header, content, footer, panels), centered when narrower than the available space. Dividers stay full-bleed. Numbers are pixels, strings are used as-is (e.g. `60ch`). Common page widths: 640 for forms, settings, and text-focused pages; 960 for content pages and wider layouts.',
+    },
+    {
+      name: 'padding',
+      type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',
+      description:
+        "Padding at the layout's outer edges using the spacing scale.",
+    },
+    {
+      name: 'defaultHasDividers',
+      type: 'boolean',
+      description:
+        "Default divider visibility for LayoutHeader and LayoutFooter children. Headers and footers that don't pass `hasDivider` use this value; when unset, nested layouts inherit from their parent context.",
+    },
   ],
   components: [
     {name: 'LayoutHeader'},

package/src/Layout/container.stylex.ts

@@ -28,8 +28,10 @@
  * }
  * ```
  *
- * Internal variables (`--layout-padding-inner-x`, `--container-padding-*`)
- * are implementation details and must not be referenced by themes.
+ * Internal variables (`--layout-padding-inner-x`, `--container-padding-*`,
+ * `--_section-padding-propagated`) are implementation details and must not be
+ * referenced by themes. They also do not cross an overlay boundary — see
+ * `overlayPaddingReset` in padding.stylex.ts.
  *
  * SYNC: When modified, update /packages/core/src/Layout/Layout.doc.mjs
  */
@@ -105,7 +107,13 @@ const cardBlockEnd = `var(--astryx-card-padding-block-end, ${cardShorthand})`;
 // Section padding chains: --astryx-* then the next specificity level, terminating
 // at --spacing-4. Built as chained const strings (no function calls) so StyleX
 // can statically analyze them; see naming.ts for the prefix policy.
-const sectionShorthand = `var(--astryx-section-padding, ${SP4})`;
+// `--_section-padding-propagated` (set by an ancestor Section with explicit
+// padding) is read AHEAD of the public theme token, so a propagated value
+// still wins over the theme for nested sections. Splitting the two names is
+// what lets an overlay drop the inherited value at its boundary while keeping
+// the theme's — see `overlayPaddingReset` in padding.stylex.ts.
+const sectionThemeShorthand = `var(--astryx-section-padding, ${SP4})`;
+const sectionShorthand = `var(--_section-padding-propagated, ${sectionThemeShorthand})`;
 const sectionInline = `var(--astryx-section-padding-inline, ${sectionShorthand})`;
 const sectionInlineStart = `var(--astryx-section-padding-inline-start, ${sectionInline})`;
 const sectionInlineEnd = `var(--astryx-section-padding-inline-end, ${sectionInline})`;

package/src/Layout/index.ts

@@ -19,6 +19,10 @@ export type {
   SpacingToken,
 } from './container.stylex';
 
+// Overlay padding-variable reset (applied on overlay roots so the container
+// padding system does not cross a fixed/top-layer boundary)
+export {overlayPaddingReset} from './padding.stylex';
+
 // Edge compensation utility
 export {edgeCompSlot, EDGE_COMP_ATTR} from './edgeCompensation.stylex';
 

package/src/Layout/overlayPaddingReset.test.tsx

@@ -0,0 +1,222 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file overlayPaddingReset.test.tsx
+ * @input Uses vitest, @testing-library/react, overlay components from core
+ * @output Tests that overlay roots stop the container padding system at their
+ *   boundary, and that the public theme token still crosses it
+ * @position Layout tests; validates overlayPaddingReset in padding.stylex.ts
+ *
+ * The container padding system talks to descendants through INHERITED custom
+ * properties, but an overlay leaves its parent's visual box while staying a DOM
+ * descendant of it. Every overlay root therefore has to stop those values (see
+ * #5208: a Section in a 640px sheet rendered 672px wide).
+ *
+ * jsdom does no layout, so these assert on the custom properties themselves —
+ * the definitions the layout is computed from. The widths they stand in for are
+ * verified in a browser; see the PR description.
+ *
+ * SYNC: When an overlay is added, add it to OVERLAYS below.
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {render, screen} from '@testing-library/react';
+import type {ReactNode} from 'react';
+import {Dialog} from '../Dialog';
+import {BottomSheet} from '../BottomSheet';
+import {MobileNav} from '../MobileNav';
+import {Lightbox} from '../Lightbox';
+import {Popover} from '../Popover';
+import {Section} from '../Section';
+
+// jsdom implements neither the <dialog> methods nor matchMedia.
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.show = vi.fn(function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockReturnValue({
+      matches: false,
+      media: '',
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }),
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+/**
+ * Values descendants SUBTRACT (bleed margins). The overlay root has no padding
+ * of its own to escape, so these must read a literal zero.
+ */
+const SUBTRACTED = [
+  '--container-padding-inline-start',
+  '--container-padding-inline-end',
+  '--container-padding-block-start',
+  '--container-padding-block-end',
+];
+
+/**
+ * Values descendants ADD. These must be guaranteed-invalid (`initial`) rather
+ * than zero, so readers fall through to their own default instead of losing
+ * their padding — a computed empty string is what `initial` looks like here.
+ */
+const CLEARED = [
+  '--layout-padding-outer-x',
+  '--layout-padding-outer-y',
+  '--layout-padding-inner-x',
+  '--layout-padding-inner-y',
+  '--_section-padding-propagated',
+];
+
+/** What a cleared custom property reads back as. See the assertion below. */
+const CLEARED_READBACK = ['', 'initial'];
+
+/** Each overlay, rendered open inside a page Section that leaks 40px. */
+const OVERLAYS: {
+  name: string;
+  render: (child: ReactNode) => ReactNode;
+  root: () => HTMLElement;
+}[] = [
+  {
+    name: 'Dialog',
+    render: child => (
+      <Dialog isOpen onOpenChange={() => {}}>
+        {child}
+      </Dialog>
+    ),
+    root: () => screen.getByRole('dialog'),
+  },
+  {
+    name: 'BottomSheet',
+    render: child => (
+      <BottomSheet isOpen onOpenChange={() => {}} label="S">
+        {child}
+      </BottomSheet>
+    ),
+    root: () =>
+      document.querySelector<HTMLElement>(
+        '.astryx-bottom-sheet',
+      ) as HTMLElement,
+  },
+  {
+    name: 'MobileNav',
+    render: child => (
+      <MobileNav isOpen onOpenChange={() => {}} label="N">
+        {child}
+      </MobileNav>
+    ),
+    root: () => screen.getByRole('dialog'),
+  },
+  {
+    name: 'Lightbox',
+    render: () => (
+      <Lightbox
+        isOpen
+        onOpenChange={() => {}}
+        media={{src: 'a.png', alt: 'a'}}
+      />
+    ),
+    root: () => screen.getByRole('dialog'),
+  },
+  {
+    name: 'Popover (useLayer surface)',
+    render: child => (
+      <Popover isOpen onOpenChange={() => {}} label="P" content={child}>
+        <button type="button">t</button>
+      </Popover>
+    ),
+    root: () => document.querySelector<HTMLElement>('[popover]') as HTMLElement,
+  },
+];
+
+describe('overlayPaddingReset', () => {
+  describe.each(OVERLAYS)('$name', ({render: renderOverlay, root}) => {
+    it('zeroes the values descendants subtract', () => {
+      render(<Section padding={10}>{renderOverlay(<div>c</div>)}</Section>);
+      const computed = getComputedStyle(root());
+      for (const name of SUBTRACTED) {
+        expect(computed.getPropertyValue(name), name).toBe('0px');
+      }
+    });
+
+    it('clears the values descendants add, so they fall to their default', () => {
+      render(<Section padding={10}>{renderOverlay(<div>c</div>)}</Section>);
+      const computed = getComputedStyle(root());
+      for (const name of CLEARED) {
+        // A browser resolves `initial` on a custom property to the
+        // guaranteed-invalid value and reports '' here; jsdom does not
+        // implement that and echoes the keyword. Either proves the
+        // declaration landed — and neither is the leaked '40px'.
+        expect(CLEARED_READBACK, name).toContain(
+          computed.getPropertyValue(name),
+        );
+      }
+    });
+  });
+
+  it('does not clear the public theme token', () => {
+    // The reset clears the PRIVATE propagation var only. The public
+    // `--astryx-section-padding` is theme surface, set once at the theme root,
+    // so it has to keep reaching inside every overlay — clearing it would
+    // blank a theme's section padding in every dialog. That is the whole
+    // reason the two names were split, and it is the mistake a later
+    // "simplification" would most plausibly make.
+    //
+    // jsdom does not inherit custom properties, so the cascade cannot show
+    // this; assert it where it is decided instead. (Verified in a browser: a
+    // theme's 20px still reaches a Section inside a Dialog nested under a
+    // 40px page Section.)
+    const source = readFileSync(join(__dirname, 'padding.stylex.ts'), 'utf8');
+    const reset = source.slice(
+      source.indexOf('export const overlayPaddingReset'),
+    );
+    expect(reset).toContain("'--_section-padding-propagated': 'initial'");
+    expect(reset).not.toContain('--astryx-section-padding');
+  });
+
+  it("stops an ancestor Section's propagated padding at the boundary", () => {
+    // The page Section propagates 40px. Without the reset it would reach the
+    // Section inside the overlay, which would pad itself 40px instead of the
+    // theme default — the second half of #5208.
+    render(
+      <Section padding={10}>
+        <Dialog isOpen onOpenChange={() => {}}>
+          <div data-testid="content">c</div>
+        </Dialog>
+      </Section>,
+    );
+    const dialog = screen.getByRole('dialog');
+    expect(CLEARED_READBACK).toContain(
+      getComputedStyle(dialog).getPropertyValue(
+        '--_section-padding-propagated',
+      ),
+    );
+    // ...while the page Section outside the overlay still propagates it.
+    // (jsdom does not resolve the token reference to its 40px value.)
+    const pageSection = document.querySelector<HTMLElement>('.astryx-section');
+    expect(
+      getComputedStyle(pageSection as HTMLElement).getPropertyValue(
+        '--_section-padding-propagated',
+      ),
+    ).toBe('var(--spacing-10)');
+  });
+});

package/src/Layout/padding.stylex.ts

@@ -326,21 +326,201 @@ export const paddingBlockStyles = stylex.create({
 });
 
 /**
- * Propagation styles for --astryx-section-padding.
+ * Inline-start-only padding override styles.
+ * Use when a component needs to override the inline-start edge independently
+ * of inline-end. Logical, so it follows the writing direction (left in LTR,
+ * right in RTL).
+ */
+export const paddingInlineStartStyles = stylex.create({
+  0: {paddingInlineStart: spacingVars['--spacing-0']},
+  0.5: {paddingInlineStart: spacingVars['--spacing-0-5']},
+  1: {paddingInlineStart: spacingVars['--spacing-1']},
+  1.5: {paddingInlineStart: spacingVars['--spacing-1-5']},
+  2: {paddingInlineStart: spacingVars['--spacing-2']},
+  3: {paddingInlineStart: spacingVars['--spacing-3']},
+  4: {paddingInlineStart: spacingVars['--spacing-4']},
+  5: {paddingInlineStart: spacingVars['--spacing-5']},
+  6: {paddingInlineStart: spacingVars['--spacing-6']},
+  8: {paddingInlineStart: spacingVars['--spacing-8']},
+  10: {paddingInlineStart: spacingVars['--spacing-10']},
+});
+
+/**
+ * Inline-end-only padding override styles.
+ * The inline-end counterpart of paddingInlineStartStyles.
+ */
+export const paddingInlineEndStyles = stylex.create({
+  0: {paddingInlineEnd: spacingVars['--spacing-0']},
+  0.5: {paddingInlineEnd: spacingVars['--spacing-0-5']},
+  1: {paddingInlineEnd: spacingVars['--spacing-1']},
+  1.5: {paddingInlineEnd: spacingVars['--spacing-1-5']},
+  2: {paddingInlineEnd: spacingVars['--spacing-2']},
+  3: {paddingInlineEnd: spacingVars['--spacing-3']},
+  4: {paddingInlineEnd: spacingVars['--spacing-4']},
+  5: {paddingInlineEnd: spacingVars['--spacing-5']},
+  6: {paddingInlineEnd: spacingVars['--spacing-6']},
+  8: {paddingInlineEnd: spacingVars['--spacing-8']},
+  10: {paddingInlineEnd: spacingVars['--spacing-10']},
+});
+
+/**
+ * Container padding inline-start CSS variable style, set independently of
+ * inline-end so a per-edge override keeps edge-compensating children (Card,
+ * Divider, a nested Section) compensating against the padding actually
+ * applied on that edge.
+ */
+export const containerPaddingInlineStartVarStyles = stylex.create({
+  0: {'--container-padding-inline-start': spacingVars['--spacing-0']},
+  0.5: {'--container-padding-inline-start': spacingVars['--spacing-0-5']},
+  1: {'--container-padding-inline-start': spacingVars['--spacing-1']},
+  1.5: {'--container-padding-inline-start': spacingVars['--spacing-1-5']},
+  2: {'--container-padding-inline-start': spacingVars['--spacing-2']},
+  3: {'--container-padding-inline-start': spacingVars['--spacing-3']},
+  4: {'--container-padding-inline-start': spacingVars['--spacing-4']},
+  5: {'--container-padding-inline-start': spacingVars['--spacing-5']},
+  6: {'--container-padding-inline-start': spacingVars['--spacing-6']},
+  8: {'--container-padding-inline-start': spacingVars['--spacing-8']},
+  10: {'--container-padding-inline-start': spacingVars['--spacing-10']},
+});
+
+/**
+ * Container padding inline-end CSS variable style, the counterpart of
+ * containerPaddingInlineStartVarStyles.
+ */
+export const containerPaddingInlineEndVarStyles = stylex.create({
+  0: {'--container-padding-inline-end': spacingVars['--spacing-0']},
+  0.5: {'--container-padding-inline-end': spacingVars['--spacing-0-5']},
+  1: {'--container-padding-inline-end': spacingVars['--spacing-1']},
+  1.5: {'--container-padding-inline-end': spacingVars['--spacing-1-5']},
+  2: {'--container-padding-inline-end': spacingVars['--spacing-2']},
+  3: {'--container-padding-inline-end': spacingVars['--spacing-3']},
+  4: {'--container-padding-inline-end': spacingVars['--spacing-4']},
+  5: {'--container-padding-inline-end': spacingVars['--spacing-5']},
+  6: {'--container-padding-inline-end': spacingVars['--spacing-6']},
+  8: {'--container-padding-inline-end': spacingVars['--spacing-8']},
+  10: {'--container-padding-inline-end': spacingVars['--spacing-10']},
+});
+
+/**
+ * Block-start-only padding override styles.
+ * Use when a component needs to override the block-start (top) edge
+ * independently of block-end — e.g. a section that sits under a sticky
+ * header and needs less padding above than below.
+ */
+export const paddingBlockStartStyles = stylex.create({
+  0: {paddingBlockStart: spacingVars['--spacing-0']},
+  0.5: {paddingBlockStart: spacingVars['--spacing-0-5']},
+  1: {paddingBlockStart: spacingVars['--spacing-1']},
+  1.5: {paddingBlockStart: spacingVars['--spacing-1-5']},
+  2: {paddingBlockStart: spacingVars['--spacing-2']},
+  3: {paddingBlockStart: spacingVars['--spacing-3']},
+  4: {paddingBlockStart: spacingVars['--spacing-4']},
+  5: {paddingBlockStart: spacingVars['--spacing-5']},
+  6: {paddingBlockStart: spacingVars['--spacing-6']},
+  8: {paddingBlockStart: spacingVars['--spacing-8']},
+  10: {paddingBlockStart: spacingVars['--spacing-10']},
+});
+
+/**
+ * Block-end-only padding override styles.
+ * The block-end counterpart of paddingBlockStartStyles.
+ */
+export const paddingBlockEndStyles = stylex.create({
+  0: {paddingBlockEnd: spacingVars['--spacing-0']},
+  0.5: {paddingBlockEnd: spacingVars['--spacing-0-5']},
+  1: {paddingBlockEnd: spacingVars['--spacing-1']},
+  1.5: {paddingBlockEnd: spacingVars['--spacing-1-5']},
+  2: {paddingBlockEnd: spacingVars['--spacing-2']},
+  3: {paddingBlockEnd: spacingVars['--spacing-3']},
+  4: {paddingBlockEnd: spacingVars['--spacing-4']},
+  5: {paddingBlockEnd: spacingVars['--spacing-5']},
+  6: {paddingBlockEnd: spacingVars['--spacing-6']},
+  8: {paddingBlockEnd: spacingVars['--spacing-8']},
+  10: {paddingBlockEnd: spacingVars['--spacing-10']},
+});
+
+/**
+ * Propagation styles for `--_section-padding-propagated`.
  * When a parent section sets explicit padding, this propagates the value
  * through the CSS custom property cascade so nested sections that use
  * useThemeDefault inherit the parent's padding instead of the theme default.
+ *
+ * This is deliberately NOT the public `--astryx-section-padding` token. The
+ * two carry different authority: the public token is the THEME's section
+ * padding, set once at the theme root, while this one is one ancestor
+ * Section's padding, propagated down the tree. An overlay has to drop the
+ * inherited value at its boundary (see {@link overlayPaddingReset}) without
+ * dropping the theme's — impossible while both live under one name.
+ * `container.stylex.ts` reads this ahead of the public token, so a propagated
+ * value still wins over the theme for nested sections, as before.
  */
 export const sectionPaddingPropagationStyles = stylex.create({
-  0: {'--astryx-section-padding': spacingVars['--spacing-0']},
-  0.5: {'--astryx-section-padding': spacingVars['--spacing-0-5']},
-  1: {'--astryx-section-padding': spacingVars['--spacing-1']},
-  1.5: {'--astryx-section-padding': spacingVars['--spacing-1-5']},
-  2: {'--astryx-section-padding': spacingVars['--spacing-2']},
-  3: {'--astryx-section-padding': spacingVars['--spacing-3']},
-  4: {'--astryx-section-padding': spacingVars['--spacing-4']},
-  5: {'--astryx-section-padding': spacingVars['--spacing-5']},
-  6: {'--astryx-section-padding': spacingVars['--spacing-6']},
-  8: {'--astryx-section-padding': spacingVars['--spacing-8']},
-  10: {'--astryx-section-padding': spacingVars['--spacing-10']},
+  0: {'--_section-padding-propagated': spacingVars['--spacing-0']},
+  0.5: {'--_section-padding-propagated': spacingVars['--spacing-0-5']},
+  1: {'--_section-padding-propagated': spacingVars['--spacing-1']},
+  1.5: {'--_section-padding-propagated': spacingVars['--spacing-1-5']},
+  2: {'--_section-padding-propagated': spacingVars['--spacing-2']},
+  3: {'--_section-padding-propagated': spacingVars['--spacing-3']},
+  4: {'--_section-padding-propagated': spacingVars['--spacing-4']},
+  5: {'--_section-padding-propagated': spacingVars['--spacing-5']},
+  6: {'--_section-padding-propagated': spacingVars['--spacing-6']},
+  8: {'--_section-padding-propagated': spacingVars['--spacing-8']},
+  10: {'--_section-padding-propagated': spacingVars['--spacing-10']},
+});
+
+/**
+ * Padding-variable reset for overlay roots (Dialog, BottomSheet, Drawer,
+ * MobileNav, Lightbox, and every layer surface).
+ *
+ * ## Why an overlay needs this
+ *
+ * The container padding system talks to descendants through inherited custom
+ * properties: a padded container announces its padding, and children read the
+ * value either to apply it or to cancel it with a negative margin
+ * (`Section`, `Divider`, `Layout`, `Table`).
+ *
+ * Inheritance follows the DOM, but an overlay leaves its parent's visual box —
+ * a fixed/top-layer `<dialog>` is a DOM descendant of the padded page while
+ * being nowhere near it on screen. It inherits values describing padding that
+ * is not there, and its content compensates against phantom space: a `Section`
+ * inside a 640px sheet rendered 672px wide and hung off both edges (#5208).
+ *
+ * Two families leak, and they need opposite treatments:
+ *
+ * - `--container-padding-*` -> `0px`. Descendants SUBTRACT these (bleed
+ *   margins). The overlay root has no padding of its own to escape, so the
+ *   honest answer is zero. Nested containers that do set padding (a Dialog's
+ *   content wrapper) re-announce their own values below this point, so
+ *   legitimate edge-to-edge bleed inside the overlay is unaffected.
+ * - `--layout-padding-*` and `--_section-padding-propagated` -> `initial`.
+ *   Descendants ADD these, so zeroing them would strip padding rather than
+ *   restore it. `initial` makes each guaranteed-invalid, so readers fall
+ *   through their own `var(…, fallback)` chain and land on the theme default —
+ *   which is what an overlay at the top of the tree should show.
+ *
+ * `initial` is also why propagation moved off `--astryx-section-padding`: that
+ * name is public theme surface, set at the theme root, and making it invalid
+ * here would blank the theme's own section padding inside every overlay.
+ *
+ * Apply on the overlay's outermost styled element.
+ *
+ * @example
+ * ```
+ * <dialog {...stylex.props(styles.dialog, overlayPaddingReset.reset)} />
+ * ```
+ */
+export const overlayPaddingReset = stylex.create({
+  reset: {
+    // Subtracted by descendants — the overlay root has no padding to escape.
+    '--container-padding-inline-start': '0px',
+    '--container-padding-inline-end': '0px',
+    '--container-padding-block-start': '0px',
+    '--container-padding-block-end': '0px',
+    // Added by descendants — fall through to each reader's own default.
+    '--layout-padding-outer-x': 'initial',
+    '--layout-padding-outer-y': 'initial',
+    '--layout-padding-inner-x': 'initial',
+    '--layout-padding-inner-y': 'initial',
+    '--_section-padding-propagated': 'initial',
+  },
 });

package/src/Lightbox/Lightbox.tsx

@@ -36,6 +36,7 @@ import {mergeProps, mergeRefs, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {overlayPaddingReset} from '../Layout/padding.stylex';
 import {useTranslator} from '../i18n';
 
 /**
@@ -588,7 +589,7 @@ export function Lightbox({
       aria-label={currentItem.alt || t('@astryx.lightbox.mediaViewer')}
       {...mergeProps(
         themeProps('lightbox'),
-        stylex.props(styles.dialog, xstyle),
+        stylex.props(styles.dialog, overlayPaddingReset.reset, xstyle),
         className,
         style,
       )}