Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(AppShell): AppShell is a layout root; nothing an ancestor Layout, Card or Section passes down reaches its regions (#9418)

Cindy Zhang4f4795a6171e
diff --git a/.changeset/appshell-layout-root.md b/.changeset/appshell-layout-root.md
new file mode 100644
index 0000000000..ad88b3f7ee
--- /dev/null
+++ b/.changeset/appshell-layout-root.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `AppShell` is a layout root: the layout values its ancestors pass down stop at its root, so it lays out the same inside a padded `Card`, a `Section` or a `Layout` as at the page root. Before, its internal Layout escaped a padded host's padding on all four sides, so in a padded `Card` that clips its overflow the shell's logo was cut at the inline start and its navigation and content at the other edges. A caller's own props and styles on `AppShell` still apply; theme, color mode, direction and translations keep inheriting.
+
+@cixzhang @duytbp
diff --git a/apps/docsite/src/__tests__/example-layout-root.test.ts b/apps/docsite/src/__tests__/example-layout-root.test.ts
new file mode 100644
index 0000000000..af4661301e
--- /dev/null
+++ b/apps/docsite/src/__tests__/example-layout-root.test.ts
@@ -0,0 +1,49 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Docsite example root follows Layout's reset (component:Layout FR8).
+ *
+ * The example root in ExampleBlock cannot import Core's internal
+ * `layoutReset` (Core's `./internal/*` is reserved for Core and Lab), so it
+ * composes the public `overlayPaddingReset` and mirrors the rest. This test
+ * fails when the mirror and Layout's reset differ, so Layout stays the one
+ * owner and the docs examples follow it.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {describe, expect, it} from 'vitest';
+
+const REPO = path.resolve(__dirname, '../../../..');
+const read = (file: string) => fs.readFileSync(path.join(REPO, file), 'utf8');
+
+/** The custom-property declarations inside the object literal after `marker`. */
+function declarations(source: string, marker: string): Record<string, string> {
+ const start = source.indexOf(marker);
+ expect(start, marker).toBeGreaterThanOrEqual(0);
+ const body = source.slice(start, source.indexOf('},', start));
+ return Object.fromEntries(
+ Array.from(body.matchAll(/'(--[\w-]+)':\s*'([^']*)'/g), m => [m[1], m[2]]),
+ );
+}
+
+describe('docsite example root (component:Layout FR8)', () => {
+ const layoutReset = read('packages/core/src/Layout/layoutReset.ts');
+ const exampleBlock = read(
+ 'apps/docsite/src/components/component-detail/ExampleBlock.tsx',
+ );
+
+ it('composes the same public reset that Layout composes', () => {
+ expect(layoutReset).toMatch(/overlayPaddingReset\.reset,/);
+ expect(exampleBlock).toMatch(
+ /stylex\.props\(overlayPaddingReset\.reset, styles\.exampleRoot\)/,
+ );
+ });
+
+ it('mirrors the rest of Layout reset, name for name and value for value', () => {
+ const owner = declarations(layoutReset, 'const resetBeyondOverlays');
+ const mirror = declarations(exampleBlock, 'exampleRoot:');
+ expect(Object.keys(owner).length).toBeGreaterThan(0);
+ expect(mirror).toEqual(owner);
+ });
+});
diff --git a/apps/docsite/src/components/component-detail/ExampleBlock.tsx b/apps/docsite/src/components/component-detail/ExampleBlock.tsx
index 083bc5fc9a..c178f77ad7 100644
--- a/apps/docsite/src/components/component-detail/ExampleBlock.tsx
+++ b/apps/docsite/src/components/component-detail/ExampleBlock.tsx
@@ -44,9 +44,10 @@ const styles = stylex.create({
// Section padding propagation), the layout values the docs card publishes
// stop at the example, so it renders as it does at a page root: no Layout in
// the example escapes the card's padding, or takes its insets, widths or
- // height cap. These are the values that reset leaves out. AppShell's own
- // layout-root reset (component:AppShell FR18) is not built yet; until it is,
- // this boundary is what keeps the AppShell examples whole.
+ // height cap. These are the values that reset leaves out: a mirror of
+ // Layout's internal `layoutReset` (component:Layout FR8), which Core's
+ // `./internal/*` rule keeps the docsite from importing.
+ // example-layout-root.test.ts fails when the two differ.
exampleRoot: {
minWidth: 'fit-content',
'--layout-content-width': 'initial',
diff --git a/apps/storybook/stories/AppShell.stories.tsx b/apps/storybook/stories/AppShell.stories.tsx
index 8d91eaaabc..aa959c5b41 100644
--- a/apps/storybook/stories/AppShell.stories.tsx
+++ b/apps/storybook/stories/AppShell.stories.tsx
@@ -3,6 +3,9 @@
import {useState} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
import {AppShell} from '@astryxdesign/core/AppShell';
+import {Layout, LayoutHeader} from '@astryxdesign/core/Layout';
+import {Card} from '@astryxdesign/core/Card';
+import {Section} from '@astryxdesign/core/Section';
import {Banner} from '@astryxdesign/core/Banner';
import {Badge} from '@astryxdesign/core/Badge';
import {Button} from '@astryxdesign/core/Button';
@@ -842,6 +845,67 @@ export const WithBanner: Story = {
),
};
+/**
+ * A layout root (FR18): a With Banner shell at the page root (`host: root`)
+ * or placed in a padded Card that clips overflow, as a docs example card
+ * does (`card`), in an outer Layout's content area (`layout`), or in a
+ * Section with explicit padding (`section`). It lays out the same in each:
+ * nothing an ancestor Layout, Card or Section publishes reaches its regions.
+ */
+type LayoutHost = 'root' | 'card' | 'layout' | 'section';
+
+export const InsideLayoutHosts: StoryObj<{host: LayoutHost}> = {
+ args: {host: 'card'},
+ argTypes: {
+ host: {
+ control: 'select',
+ options: ['root', 'card', 'layout', 'section'],
+ type: {name: 'string'},
+ },
+ },
+ render: ({host}) => {
+ const shell = (
+ <AppShell
+ data-testid="shell"
+ contentPadding={6}
+ style={{height: 420}}
+ topNav={<AppTopNav />}
+ sideNav={<SideNavWithoutHeader />}
+ banner={
+ <Banner
+ status="info"
+ container="section"
+ title="System maintenance scheduled"
+ description="The system will undergo maintenance tonight at 10pm UTC."
+ isDismissable
+ />
+ }>
+ <MockContent />
+ </AppShell>
+ );
+ switch (host) {
+ case 'card':
+ return (
+ <Card padding={3} style={{overflow: 'hidden'}}>
+ {shell}
+ </Card>
+ );
+ case 'layout':
+ return (
+ <Layout
+ padding={4}
+ header={<LayoutHeader>Outer layout header</LayoutHeader>}
+ content={shell}
+ />
+ );
+ case 'section':
+ return <Section padding={6}>{shell}</Section>;
+ default:
+ return shell;
+ }
+ },
+};
+
/**
* Responsive layout with mobile navigation drawer. Shows the recommended
* pattern for apps that need to work across desktop and mobile:
diff --git a/docs/specs/components/AppShell/AppShell.spec.md b/docs/specs/components/AppShell/AppShell.spec.md
index d593bed193..c0e0c23a21 100644
--- a/docs/specs/components/AppShell/AppShell.spec.md
+++ b/docs/specs/components/AppShell/AppShell.spec.md
@@ -36,7 +36,7 @@ system_specs: [spec:AST-012, spec:AST-027]
| Behavior | One page frame: skip link, then a header region, an inline side region, and one `main` region. Below the mobile breakpoint the side nav leaves the page and AppShell composes a mobile drawer from the nav slots, unless `mobileNav` disables or replaces it. AppShell is a layout root: layout values from its ancestors stop at its root (FR18). |
| End-user impact | Keyboard users get a skip link to the main region; screen-reader users get one banner and one main landmark; phone-width users reach the side nav through a toggle and drawer while page content, its input values, and focus survive the layout switch. When the side nav collapses or expands, the content's old and new wrap swap on the rail's clock instead of re-wrapping in one frame (FR17). |
| Builder impact | None. Callers fill slots and choose height, variant, content padding, and mobile behavior. |
-| Compatibility/readiness | Records shipped behavior; no prop, default, or export changes. Five current-state gaps, listed under Current-state impact: page-level stacking values, a banner pinned against its docs, an unmeasured late header, a raw `content` drawer the toggle cannot reach, and ancestor layout values that reach the shell (FR18). |
+| Compatibility/readiness | Records shipped behavior; no prop, default, or export changes. Four current-state gaps, listed under Current-state impact: page-level stacking values, a banner pinned against its docs, an unmeasured late header, and a raw `content` drawer the toggle cannot reach. |
| Review checks | Reject a second `main` or banner landmark from AppShell, a skip link that is not the first focusable element or does not move focus to `main`, a breakpoint that treats equality as mobile, or remounting page content when the breakpoint changes. Also reject a content area that animates its width during a side nav collapse or expand (FR17), and a shell whose regions move, clip, or change inset because of a Layout, Card, Section, or other layout host around it (FR18). |
| Governing rules | `spec:AST-012` FR8 (width points), `family:layout-regions` FR9, `architecture:theme-application` INV10, `spec:AST-027` FR1–FR5 (local stacking), `architecture:component-theming-surface`; `component:SideNav` FR6 and `spec:AST-105` FR8 (the content swap); `architecture:container-padding` and `component:Layout` FR2 and FR5 (the layout root, FR18). |
@@ -89,13 +89,6 @@ Consumer migration instructions belong in consumer docs and release notes.
the auto toggle still renders, so its `aria-controls` names no element and its
presses open nothing. WCAG 4.1.2 requires a control's relationships and state
to be programmatically correct.
-- **Ancestor layout values reach the shell.** AppShell's root resets none of
- the values FR18 names. Inside a padded Card, AppShell's Layout escapes the
- card's published padding on all four edges, so in a host that clips overflow
- the shell's logo is cut at the inline-start edge and its navigation and
- content are cut at the inline-end and block-end edges; Layouts and Sections
- inside `children` take the host's inset and divider default, and an enclosing
- Layout's divider-less header can zero the main region's block-start padding.
## Ownership boundary
@@ -156,26 +149,26 @@ the only component record in the AppShell root.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
-| FR1 | The root element carries `app-shell`, the forwarded `ref`, `data-testid`, and other DOM props, and contains, in order: the skip link, the Layout frame (header region, inline side region, content region), then any mobile drawer. | Current source and tests |
-| FR2 | A slot is present when its value is renderable: not `null`, `undefined`, a boolean, or an empty string. A component that renders nothing still counts as present. | Current source and public types |
-| FR3 | The header region renders only when `topNav` or `banner` is present; it carries `app-shell-header` and `role="banner"`, places `banner` above `topNav`, and is never inside another landmark. The sidenav-only mobile top bar (FR9) also carries `app-shell-header` and takes `role="banner"` only when no header region renders. AppShell renders at most one banner landmark. | Current source and tests |
-| FR4 | `children` render in one region with `role="main"` and `id="astryx-app-shell-main"`, programmatically focusable so the skip link can move focus to it; programmatic focus on it draws no focus ring. Its padding is `contentPadding`, default `0`. Whether it is a sequential tab stop is keyboard access to a scroll region (`spec:AST-025` FR12). Focus that Tab moves onto it while it is a stop draws the standard focus ring, inset, until focus leaves it; in `elevated` with both navs the region takes the surface's rounded top-start corner while that ring shows. | Current source and tests |
-| FR5 | The skip link is the first focusable element in the shell. It links to `#astryx-app-shell-main`, shows the translated `@astryx.appShell.skipToContent` text, is visually hidden until focused, and on activation moves focus to the main region. | WCAG 2.4.1; current source and tests |
-| FR6 | `fill` sizes the root to `100dvh` and the inline side region and main region scroll on their own. `auto` gives the root a `100dvh` minimum, makes the header sticky at the block start, keeps the inline side region sticky below the measured height of a header present when the shell mounts in `auto`, with its own scrolling, and lets the page scroll. Header height is measured only in `auto`. | Current source and tests |
-| FR7 | Variant backgrounds: `wash` paints body background on the frame, nav areas, and content; `surface` paints surface on all three; `section` paints surface on the frame and divides the nav areas from content, and in `auto` the header paints surface itself; `elevated` paints body background on the frame and nav areas and surface on content (FR16 for the corner). | Current source and tests |
-| FR8 | The mobile layout follows `mobileNav.breakpoint` under `spec:AST-012` FR8 and `architecture:theme-application` INV10; the breakpoint defaults to `md`, and `defaultIsMobile` is ignored when it is `none`. | `spec:AST-012` FR8; tests |
-| FR9 | In the mobile layout the side nav leaves the inline region. A present `topNav` renders in TopNav's mobile-bar mode, given the side nav content for its drawer, unless `mobileNav` is `false` or a node. With `sideNav`, no `topNav`, `mobileNav` not `false`, and `hasToggle` not `false`, a mobile top bar renders the side nav in SideNav's top-bar mode in a navigation region named by `@astryx.appShell.mobileNavigation`; the auto toggle beside it renders only while mobile navigation is enabled (FR11), so with a drawer node the top bar has no toggle. | Current source and tests |
-| FR10 | The auto drawer renders only in the mobile layout and only when `mobileNav` is not `false`, not a node, and has no `content`. Without `topNav` it is SideNav in drawer mode; with `topNav` it is TopNav in drawer mode carrying the side nav content; with a heading-only TopNav the side nav items render exactly once. It stays mounted while closed and, after a close, is not hidden before MobileNav's close delay has elapsed (hidden at once under reduced motion); an open is visible in the commit that carries it. | Current source and tests |
-| FR11 | The drawer is closed by default and AppShell owns its state unless `mobileNav.isOpen` is defined. Every requested change calls `mobileNav.onOpenChange`. Open and toggle requests do nothing unless mobile navigation is enabled: a nav slot is present, `mobileNav` is not `false`, and `mobileNav` is not a node. | Current source and tests |
-| FR12 | `mobileNav={false}` renders no drawer and no toggle; in the mobile layout the side nav then renders neither inline nor in a drawer. A node (element or string) renders as given at every width, replaces the auto drawer, and leaves TopNav in its full mode. A config object's `content` replaces the auto drawer in the mobile layout when a nav slot is present. `hasToggle: false` removes the auto toggle. | Current source and tests |
-| FR13 | AppShell provides its subtree with: whether the mobile layout applies, whether the drawer is open, one drawer id that the toggle's `aria-controls` names and that the auto drawer, or a MobileNav passed as `content` or as the node, applies as its `id`, open, close, and toggle actions, whether mobile navigation is enabled, and whether auto toggles are enabled (`hasToggle` is not `false`; true at every width unless `hasToggle` is `false`). | Current source and tests |
-| FR14 | Main content stays mounted across the breakpoint (`family:layout-regions` FR9); in addition, input values and focus inside `children` survive in both directions. | Current source and tests |
-| FR15 | `className`, `style`, and `xstyle` merge onto the root after component styles. | Current source |
-| FR16 | With `elevated`, a present `topNav`, and an inline side nav, the content area is a raised surface whose block-start, inline-start corner uses the page radius; otherwise the content wrapper creates no layout box. | Current source and stories |
-| FR17 | While the side nav collapses or expands, the content area swaps its old wrap for its new one in place: the old wrap slides and fades out while the new wrap slides and fades in, on the side nav's one clock, `spec:AST-105` FR4's one shared motion (`springs.settle`; `component:SideNav` FR6). The old wrap is one transient copy, inert and hidden from assistive technology, removed when the swap ends (`architecture:component-style-authoring` INV7). When the old wrap is not copied, such as on a page too large to copy, no visible gap opens between the rail and the content during an expand. The content area never animates its width. Under reduced motion the swap follows `design:reduced-motion` DR2 under a coarse primary pointer and DR3 otherwise. | `spec:AST-105` FR8; `component:SideNav` FR6 |
-| FR18 | AppShell is a layout root: at its root it resets every layout value its ancestors pass down, so its header, side, and main regions lay out the same inside a padded card, inside a Layout, or at the page root. The published container padding (`--container-padding-inline-start`, `--container-padding-inline-end`, `--container-padding-block-start`, `--container-padding-block-end`) resets to zero, so AppShell's Layout escapes nothing (`component:Layout` FR2). The Layout inset and region values (`--layout-padding-outer-x`, `--layout-padding-outer-y`, `--layout-padding-own-outer-x`, `--layout-padding-own-outer-y`, `--layout-padding-inner-x`, `--layout-padding-inner-y`, `--layout-content-width`, `--layout-alignment-width`, `--_layout-flush-block-start`, `--_layout-flush-block-end`), Section padding propagation (`--_section-padding-propagated`), and the container height cap (`--container-max-height`) reset to unset, as at the page root. The Layout area, slot, and divider-default contexts (`LayoutAreaContext`, `LayoutSlotsContext`, `LayoutDividerContext`) reset to their defaults. These names are internal protocol, not theme API (`architecture:container-padding` INV1). A caller's own props and styles on AppShell (`height`, `variant`, `contentPadding`, `mobileNav`, `className`, `style`, `xstyle`) still apply after the reset (FR15). Theme tokens, color mode, writing direction, and translations keep inheriting. Implementation gap: not built. | DEC-1; `architecture:container-padding` INV6 (the same reset at overlay roots) |
+| ID | Invariant | Basis |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| FR1 | The root element carries `app-shell`, the forwarded `ref`, `data-testid`, and other DOM props, and contains, in order: the skip link, the Layout frame (header region, inline side region, content region), then any mobile drawer. | Current source and tests |
+| FR2 | A slot is present when its value is renderable: not `null`, `undefined`, a boolean, or an empty string. A component that renders nothing still counts as present. | Current source and public types |
+| FR3 | The header region renders only when `topNav` or `banner` is present; it carries `app-shell-header` and `role="banner"`, places `banner` above `topNav`, and is never inside another landmark. The sidenav-only mobile top bar (FR9) also carries `app-shell-header` and takes `role="banner"` only when no header region renders. AppShell renders at most one banner landmark. | Current source and tests |
+| FR4 | `children` render in one region with `role="main"` and `id="astryx-app-shell-main"`, programmatically focusable so the skip link can move focus to it; programmatic focus on it draws no focus ring. Its padding is `contentPadding`, default `0`. Whether it is a sequential tab stop is keyboard access to a scroll region (`spec:AST-025` FR12). Focus that Tab moves onto it while it is a stop draws the standard focus ring, inset, until focus leaves it; in `elevated` with both navs the region takes the surface's rounded top-start corner while that ring shows. | Current source and tests |
+| FR5 | The skip link is the first focusable element in the shell. It links to `#astryx-app-shell-main`, shows the translated `@astryx.appShell.skipToContent` text, is visually hidden until focused, and on activation moves focus to the main region. | WCAG 2.4.1; current source and tests |
+| FR6 | `fill` sizes the root to `100dvh` and the inline side region and main region scroll on their own. `auto` gives the root a `100dvh` minimum, makes the header sticky at the block start, keeps the inline side region sticky below the measured height of a header present when the shell mounts in `auto`, with its own scrolling, and lets the page scroll. Header height is measured only in `auto`. | Current source and tests |
+| FR7 | Variant backgrounds: `wash` paints body background on the frame, nav areas, and content; `surface` paints surface on all three; `section` paints surface on the frame and divides the nav areas from content, and in `auto` the header paints surface itself; `elevated` paints body background on the frame and nav areas and surface on content (FR16 for the corner). | Current source and tests |
+| FR8 | The mobile layout follows `mobileNav.breakpoint` under `spec:AST-012` FR8 and `architecture:theme-application` INV10; the breakpoint defaults to `md`, and `defaultIsMobile` is ignored when it is `none`. | `spec:AST-012` FR8; tests |
+| FR9 | In the mobile layout the side nav leaves the inline region. A present `topNav` renders in TopNav's mobile-bar mode, given the side nav content for its drawer, unless `mobileNav` is `false` or a node. With `sideNav`, no `topNav`, `mobileNav` not `false`, and `hasToggle` not `false`, a mobile top bar renders the side nav in SideNav's top-bar mode in a navigation region named by `@astryx.appShell.mobileNavigation`; the auto toggle beside it renders only while mobile navigation is enabled (FR11), so with a drawer node the top bar has no toggle. | Current source and tests |
+| FR10 | The auto drawer renders only in the mobile layout and only when `mobileNav` is not `false`, not a node, and has no `content`. Without `topNav` it is SideNav in drawer mode; with `topNav` it is TopNav in drawer mode carrying the side nav content; with a heading-only TopNav the side nav items render exactly once. It stays mounted while closed and, after a close, is not hidden before MobileNav's close delay has elapsed (hidden at once under reduced motion); an open is visible in the commit that carries it. | Current source and tests |
+| FR11 | The drawer is closed by default and AppShell owns its state unless `mobileNav.isOpen` is defined. Every requested change calls `mobileNav.onOpenChange`. Open and toggle requests do nothing unless mobile navigation is enabled: a nav slot is present, `mobileNav` is not `false`, and `mobileNav` is not a node. | Current source and tests |
+| FR12 | `mobileNav={false}` renders no drawer and no toggle; in the mobile layout the side nav then renders neither inline nor in a drawer. A node (element or string) renders as given at every width, replaces the auto drawer, and leaves TopNav in its full mode. A config object's `content` replaces the auto drawer in the mobile layout when a nav slot is present. `hasToggle: false` removes the auto toggle. | Current source and tests |
+| FR13 | AppShell provides its subtree with: whether the mobile layout applies, whether the drawer is open, one drawer id that the toggle's `aria-controls` names and that the auto drawer, or a MobileNav passed as `content` or as the node, applies as its `id`, open, close, and toggle actions, whether mobile navigation is enabled, and whether auto toggles are enabled (`hasToggle` is not `false`; true at every width unless `hasToggle` is `false`). | Current source and tests |
+| FR14 | Main content stays mounted across the breakpoint (`family:layout-regions` FR9); in addition, input values and focus inside `children` survive in both directions. | Current source and tests |
+| FR15 | `className`, `style`, and `xstyle` merge onto the root after component styles. | Current source |
+| FR16 | With `elevated`, a present `topNav`, and an inline side nav, the content area is a raised surface whose block-start, inline-start corner uses the page radius; otherwise the content wrapper creates no layout box. | Current source and stories |
+| FR17 | While the side nav collapses or expands, the content area swaps its old wrap for its new one in place: the old wrap slides and fades out while the new wrap slides and fades in, on the side nav's one clock, `spec:AST-105` FR4's one shared motion (`springs.settle`; `component:SideNav` FR6). The old wrap is one transient copy, inert and hidden from assistive technology, removed when the swap ends (`architecture:component-style-authoring` INV7). When the old wrap is not copied, such as on a page too large to copy, no visible gap opens between the rail and the content during an expand. The content area never animates its width. Under reduced motion the swap follows `design:reduced-motion` DR2 under a coarse primary pointer and DR3 otherwise. | `spec:AST-105` FR8; `component:SideNav` FR6 |
+| FR18 | AppShell is a layout root: at its root it applies Layout's `layoutReset` (`component:Layout` FR8), resetting every layout value its ancestors pass down, so its header, side, and main regions lay out the same inside a padded card, inside a Layout, or at the page root. The published container padding (`--container-padding-inline-start`, `--container-padding-inline-end`, `--container-padding-block-start`, `--container-padding-block-end`) resets to zero, so AppShell's Layout escapes nothing (`component:Layout` FR2). The Layout inset and region values (`--layout-padding-outer-x`, `--layout-padding-outer-y`, `--layout-padding-own-outer-x`, `--layout-padding-own-outer-y`, `--layout-padding-inner-x`, `--layout-padding-inner-y`, `--layout-content-width`, `--layout-alignment-width`, `--_layout-flush-block-start`, `--_layout-flush-block-end`), Section padding propagation (`--_section-padding-propagated`), and the container height cap (`--container-max-height`) reset to unset, as at the page root. The Layout area, slot, and divider-default contexts (`LayoutAreaContext`, `LayoutSlotsContext`, `LayoutDividerContext`) reset to their defaults. These names are internal protocol, not theme API (`architecture:container-padding` INV1). A caller's own props and styles on AppShell (`height`, `variant`, `contentPadding`, `mobileNav`, `className`, `style`, `xstyle`) still apply after the reset (FR15). Theme tokens, color mode, writing direction, and translations keep inheriting. | DEC-1; `architecture:container-padding` INV6 (the same reset at overlay roots) |
### Allowed variation
@@ -288,19 +281,19 @@ reachability, not a decision that it must stay unthemeable.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| FR1–FR4, AR1 | `AppShell.test.tsx` slot, landmark, banner, and ref suites; `AppShellMainKeyboard.a11y.browser.spec.ts` for main as a tab stop and its focus ring | Content only; each slot; mobile top bar with banner; Tab, Shift+Tab, click and skip link onto an overflowing main | A missing or duplicate landmark, or a nested banner, fails role queries. | `audit:AppShell/anatomy` |
-| FR5, AR2 | `AppShell.test.tsx` skip-link and keyboard suites | First Tab; Enter; click; translated text | Losing the href, the focus move, or tab order fails. | `audit:AppShell/accessibility` |
-| FR6, PR1 | `AppShell.test.tsx` height-mode and main keyboard access suites; `observeMainOverflow.test.ts` | `fill`, `auto`, section header in `auto`; main fitting and overflowing in `fill` | Dropping the header's sticky placement, measuring the header in `fill`, or not measuring main, fails. | `audit:AppShell/behavior` |
-| FR8 | `AppShell.test.tsx` breakpoint suites | `lg`, `xl`, `2xl`, explicit `md`, `none`; nearest, root, and built themes; SSR hint | Wrong map, inclusive edge, or `none` entering mobile fails. | `audit:AppShell/behavior` |
-| FR9–FR12 | `AppShell.test.tsx` mobile suites; `MobileNavCloseEdgeCases.test.tsx` AppShell drawer suites | Sidenav only; both navs; heading-only TopNav; custom node | A missing toggle, duplicated items, a stale drawer, or an early hide fails. | `audit:AppShell/behavior` |
-| FR13, AR3 | `AppShell.test.tsx` keyboard drawer and `useAppShellMobile` suites | Outside a shell; inside, closed and open | A wrong id link or stale state fails. | `audit:AppShell/accessibility` |
-| FR14, AR4 | `AppShell.test.tsx` breakpoint continuity test | Desktop to mobile and back with a focused input | Remounting content loses the value or focus. | `audit:AppShell/behavior` |
-| FR17 | `SideNavRailMotion.test.tsx`, `animatedLayout.boundary.test.ts`; `SideNavRailMotion.interaction.browser.spec.ts` frames of the content area during a side nav collapse (the scrolled `auto` page and `reducedMotion: 'always'` theme cases pending) | collapse and expand with an inline side nav; Reduce Motion under a coarse and under a fine primary pointer; `fill` and a scrolled `auto` page; a theme with `reducedMotion: 'always'`; a second toggle while the swap runs; an expand whose old wrap is not copied | a visible gap between the rail and the content, a content area that animates its width or moves on its own clock, an old wrap reachable by assistive technology or left after the swap, travel under Reduce Motion, anything but an opacity-only cross-fade of 200 ms or less under Reduce Motion on a coarse pointer (DR2), or any animated property under Reduce Motion on a fine pointer (DR3) fails | `audit:AppShell/behavior` |
-| FR18 | `AppShellLayoutRoot.interaction.browser.spec.ts` (pending), a real-browser geometry test of the root, header items, side region, and main region against the page-root render; `AppShell.test.tsx` layout-root suite (pending) for the reset contexts | AppShell at the page root; inside a Layout with `padding` and a divider-less header; inside a padded Card in a host that clips overflow; inside a Section with explicit padding; each with a caller `contentPadding` and `style` | A region box, inset, or main padding that differs from the page-root render, a shell clipped by its host, a Layout or Section inside `children` that takes the host's inset or divider default, or a caller prop that loses to the reset, fails | `audit:AppShell/behavior` |
-| FR7, FR16 | `AppShell.stories.tsx` and visual baselines | `elevated` with both navs, at desktop width | A changed `elevated` background or missing corner shows in visual review. | `audit:AppShell/visual` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current targets | Missing, extra, stale, or multiply assigned mappings fail repository validation. | `audit:AppShell/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1–FR4, AR1 | `AppShell.test.tsx` slot, landmark, banner, and ref suites; `AppShellMainKeyboard.a11y.browser.spec.ts` for main as a tab stop and its focus ring | Content only; each slot; mobile top bar with banner; Tab, Shift+Tab, click and skip link onto an overflowing main | A missing or duplicate landmark, or a nested banner, fails role queries. | `audit:AppShell/anatomy` |
+| FR5, AR2 | `AppShell.test.tsx` skip-link and keyboard suites | First Tab; Enter; click; translated text | Losing the href, the focus move, or tab order fails. | `audit:AppShell/accessibility` |
+| FR6, PR1 | `AppShell.test.tsx` height-mode and main keyboard access suites; `observeMainOverflow.test.ts` | `fill`, `auto`, section header in `auto`; main fitting and overflowing in `fill` | Dropping the header's sticky placement, measuring the header in `fill`, or not measuring main, fails. | `audit:AppShell/behavior` |
+| FR8 | `AppShell.test.tsx` breakpoint suites | `lg`, `xl`, `2xl`, explicit `md`, `none`; nearest, root, and built themes; SSR hint | Wrong map, inclusive edge, or `none` entering mobile fails. | `audit:AppShell/behavior` |
+| FR9–FR12 | `AppShell.test.tsx` mobile suites; `MobileNavCloseEdgeCases.test.tsx` AppShell drawer suites | Sidenav only; both navs; heading-only TopNav; custom node | A missing toggle, duplicated items, a stale drawer, or an early hide fails. | `audit:AppShell/behavior` |
+| FR13, AR3 | `AppShell.test.tsx` keyboard drawer and `useAppShellMobile` suites | Outside a shell; inside, closed and open | A wrong id link or stale state fails. | `audit:AppShell/accessibility` |
+| FR14, AR4 | `AppShell.test.tsx` breakpoint continuity test | Desktop to mobile and back with a focused input | Remounting content loses the value or focus. | `audit:AppShell/behavior` |
+| FR17 | `SideNavRailMotion.test.tsx`, `animatedLayout.boundary.test.ts`; `SideNavRailMotion.interaction.browser.spec.ts` frames of the content area during a side nav collapse (the scrolled `auto` page and `reducedMotion: 'always'` theme cases pending) | collapse and expand with an inline side nav; Reduce Motion under a coarse and under a fine primary pointer; `fill` and a scrolled `auto` page; a theme with `reducedMotion: 'always'`; a second toggle while the swap runs; an expand whose old wrap is not copied | a visible gap between the rail and the content, a content area that animates its width or moves on its own clock, an old wrap reachable by assistive technology or left after the swap, travel under Reduce Motion, anything but an opacity-only cross-fade of 200 ms or less under Reduce Motion on a coarse pointer (DR2), or any animated property under Reduce Motion on a fine pointer (DR3) fails | `audit:AppShell/behavior` |
+| FR18 | `AppShellLayoutRoot.interaction.browser.spec.ts`, a real-browser geometry test of the Layout overhang, header logo, side region, and main region against the page-root render at desktop and phone widths, over the Inside Layout Hosts story; `AppShell.test.tsx` "AppShell layout root (FR18)" suite for the reset values, the reset contexts, and a caller style; `layoutReset.test.tsx` for the reset's coverage (`component:Layout` FR8) | AppShell at the page root; inside a Layout with `padding` and a divider-less header; inside a padded Card in a host that clips overflow; inside a Section with explicit padding; each with a caller `contentPadding` and `style` | A region box, inset, or main padding that differs from the page-root render, a shell clipped by its host, a Layout or Section inside `children` that takes the host's inset or divider default, or a caller prop that loses to the reset, fails | `audit:AppShell/behavior` |
+| FR7, FR16 | `AppShell.stories.tsx` and visual baselines | `elevated` with both navs, at desktop width | A changed `elevated` background or missing corner shows in visual review. | `audit:AppShell/visual` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current targets | Missing, extra, stale, or multiply assigned mappings fail repository validation. | `audit:AppShell/theming` |
Read from source, with no focused test or baseline yet:
diff --git a/docs/specs/components/Layout/Layout.spec.md b/docs/specs/components/Layout/Layout.spec.md
index 6b64532b4e..e1bddd41b2 100644
--- a/docs/specs/components/Layout/Layout.spec.md
+++ b/docs/specs/components/Layout/Layout.spec.md
@@ -121,9 +121,10 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR2 | The outer `div` escapes the parent's published container padding on all four edges, and the inner stack publishes zero container padding before its regions publish their own. `fill` (the default) makes the Layout fill its container's height, including the escaped block padding; `auto` lets it grow with content, at least as tall as its container. | Current source and tests; `architecture:container-padding` |
| FR3 | `padding` sets the inset that this Layout's own region components apply at its outer edges; `0` is full bleed. A nested Layout does not inherit a parent Layout's padding: without its own `padding`, its regions use the nearest padding container's padding (Card, Section, Dialog, Drawer, or BottomSheet), or spacing step 4. How each region applies and publishes that inset is owned by its record (`component:LayoutHeader`, `component:LayoutContent`, `component:LayoutFooter`, `component:LayoutPanel`). | Current source, docs, and tests; `family:layout-regions` FR4; `architecture:container-padding` |
| FR4 | When the caller supplies LayoutHeader, LayoutContent, LayoutFooter, or LayoutPanel, that component carries its own `layout-header`, `layout-content`, `layout-footer`, or `layout-panel` target. LayoutPanel at logical start, end, or both is one Panel part and one `layout-panel` target. | Current source, docs, and tests; `family:layout-regions` FR11 |
-| FR5 | `defaultHasDividers` sets the divider default for LayoutHeader and LayoutFooter descendants; an explicit `hasDivider` wins, and when unset a nested Layout keeps its parent's default within the same layer; the default stops at a Dialog, Drawer, BottomSheet, or other layer boundary (`spec:AST-038` FR7), and at an AppShell root (`component:AppShell` FR18; implementation gap: not built). LayoutPanel does not read the default (`component:LayoutPanel` FR4). | Current source, docs, and tests |
+| FR5 | `defaultHasDividers` sets the divider default for LayoutHeader and LayoutFooter descendants; an explicit `hasDivider` wins, and when unset a nested Layout keeps its parent's default within the same layer; the default stops at a Dialog, Drawer, BottomSheet, or other layer boundary (`spec:AST-038` FR7), and at an AppShell root (`component:AppShell` FR18). LayoutPanel does not read the default (`component:LayoutPanel` FR4). | Current source, docs, and tests |
| FR6 | With `contentWidth` and no panels, LayoutContent spans the middle area and aligns its direct children to the content width, so its scrollbar stays at the outer edge. With exactly one panel, the panel stays aligned while LayoutContent extends through the opposite open side; start and end mirror. With both panels, or a percentage (including percentage-bearing CSS math), intrinsic, or bare-variable width, the whole middle composition stays constrained; a length-valued variable uses `calc(var(...))`. Numbers are pixels. A nested Layout without `contentWidth` does not inherit its parent's. | Current source, docs, and tests; `family:layout-regions` FR12 |
| FR7 | `ref`, DOM, data, ARIA, and event props, `xstyle`, `className`, and `style` reach or compose on the outer `div`; the reflected `data-height` replaces a caller's value. | Current source and tests; `architecture:public-component-api` INV5–INV8 |
+| FR8 | Layout owns the layout reset: one internal export, `layoutReset` (Core's `overlayPaddingReset` plus the values it leaves out), stops at the element it is applied to every layout custom property Layout, its region components, Section, and the container styles publish to descendants. It sets the published container padding to `0px` and the Layout insets and widths, flush values, Section padding propagation, and the container height cap to `initial`. A layout root applies it (`component:AppShell` FR18). It is internal, not theme API or a package export (`architecture:container-padding` INV1, `architecture:public-component-api` INV12). A surface outside Core that needs the same boundary keeps a mirror of its list under a parity test against it. | `component:AppShell` FR18; `architecture:container-padding` |
### Allowed variation
@@ -208,17 +209,18 @@ Panel stands for every LayoutPanel, at logical start, end, or both.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
-| FR1, ORD1, AV1 | `Layout.test.tsx` slot and content tests; `childrenAsContent.test.tsx` | Every slot; omitted slots; `content` and `children` | A missing slot or `children` beating `content` fails. Gap: the omitted-slot test checks only the content text, so a wrapper rendered for an omitted slot passes, and no test asserts that slot content gains no target or element. No test covers a `false` slot. | `audit:Layout/anatomy` |
-| FR2 | `Layout.test.tsx` height-reflection tests | `fill`, `auto` | A lost `data-height` reflection fails. Gap: the escape margins, the zero publication, and the fill and auto heights have no automated check. | `audit:Layout/layout` |
-| FR3, ORD2 | `nestedPadding.test.tsx` | Inside AppShell, Card, Section; nested full-bleed and padded Layouts; explicit nested padding | A nested Layout inheriting a parent Layout's padding, or losing the enclosing Card or Section padding or the default inset, fails. Gap: `Layout.test.tsx` padding tests assert only that rendering succeeds. | `audit:Layout/layout` |
-| FR4 | `LayoutSlots.test.tsx` class tests; `themingTargets.test.ts` | Each region component; start and end panels | A lost region target fails. | `audit:Layout/theming` |
-| FR5, ORD3 | `Layout.test.tsx` divider-default tests | Default true; unset; explicit `false` | A header or footer that ignores the default, or an explicit `hasDivider={false}` that loses, fails. Gap: nested inheritance has no check. No test covers the default stopping at a layer boundary. | `audit:Layout/layout` |
-| FR6 | `contentWidth.test.tsx`; stable visual baseline `core-layout--content-width-scrollbar-placement` | No panels, start only, end only, both; zero padding; nested | A no-panel content region that is not full width, a both-panel middle that is not constrained, or a nested Layout inheriting content width fails; a scrollbar moved off its content edge comes back changed for review. No test covers a `false` start or end slot. | `audit:Layout/layout` |
-| FR7 | `Layout.test.tsx` ref, className, style, passthrough, and owned-metadata tests | Ref; caller inputs; colliding `data-height` | A ref on another element, a dropped caller input, or a caller `data-height` that wins fails. Gap: no test covers event props or the `xstyle` merge order. | `audit:Layout/api` |
-| AR1, AR2, PR1 | Source review | Every slot | Gap: no automated check fails if Layout adds a role, reorders slots, or adds a listener or measurement. | `audit:Layout/accessibility` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current targets | Missing, extra, or stale mappings fail repository validation. | `audit:Layout/theming` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1, ORD1, AV1 | `Layout.test.tsx` slot and content tests; `childrenAsContent.test.tsx` | Every slot; omitted slots; `content` and `children` | A missing slot or `children` beating `content` fails. Gap: the omitted-slot test checks only the content text, so a wrapper rendered for an omitted slot passes, and no test asserts that slot content gains no target or element. No test covers a `false` slot. | `audit:Layout/anatomy` |
+| FR2 | `Layout.test.tsx` height-reflection tests | `fill`, `auto` | A lost `data-height` reflection fails. Gap: the escape margins, the zero publication, and the fill and auto heights have no automated check. | `audit:Layout/layout` |
+| FR3, ORD2 | `nestedPadding.test.tsx` | Inside AppShell, Card, Section; nested full-bleed and padded Layouts; explicit nested padding | A nested Layout inheriting a parent Layout's padding, or losing the enclosing Card or Section padding or the default inset, fails. Gap: `Layout.test.tsx` padding tests assert only that rendering succeeds. | `audit:Layout/layout` |
+| FR4 | `LayoutSlots.test.tsx` class tests; `themingTargets.test.ts` | Each region component; start and end panels | A lost region target fails. | `audit:Layout/theming` |
+| FR5, ORD3 | `Layout.test.tsx` divider-default tests | Default true; unset; explicit `false` | A header or footer that ignores the default, or an explicit `hasDivider={false}` that loses, fails. Gap: nested inheritance has no check. No test covers the default stopping at a layer boundary. | `audit:Layout/layout` |
+| FR6 | `contentWidth.test.tsx`; stable visual baseline `core-layout--content-width-scrollbar-placement` | No panels, start only, end only, both; zero padding; nested | A no-panel content region that is not full width, a both-panel middle that is not constrained, or a nested Layout inheriting content width fails; a scrollbar moved off its content edge comes back changed for review. No test covers a `false` start or end slot. | `audit:Layout/layout` |
+| FR7 | `Layout.test.tsx` ref, className, style, passthrough, and owned-metadata tests | Ref; caller inputs; colliding `data-height` | A ref on another element, a dropped caller input, or a caller `data-height` that wins fails. Gap: no test covers event props or the `xstyle` merge order. | `audit:Layout/api` |
+| FR8 | `layoutReset.test.tsx`, which fails when Layout or Section writes a layout custom property the reset does not stop, and reads each reset value back inside a padded Section; the docsite's `example-layout-root.test.ts`, which fails when the docsite example root's mirror differs from the reset | Every custom property Layout and Section write; a padded Section host | A property written but not reset, a reset value an ancestor still overrides, or a docsite mirror that differs from the reset, fails. | `audit:Layout/layout` |
+| AR1, AR2, PR1 | Source review | Every slot | Gap: no automated check fails if Layout adds a role, reorders slots, or adds a listener or measurement. | `audit:Layout/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current targets | Missing, extra, or stale mappings fail repository validation. | `audit:Layout/theming` |
## Decision log
diff --git a/packages/core/src/AppShell/AppShell.test.tsx b/packages/core/src/AppShell/AppShell.test.tsx
index a7c059e2c1..635d578804 100644
--- a/packages/core/src/AppShell/AppShell.test.tsx
+++ b/packages/core/src/AppShell/AppShell.test.tsx
@@ -18,10 +18,20 @@ import {
beforeEach,
afterEach,
} from 'vitest';
+import {use} from 'react';
import {renderToString} from 'react-dom/server';
import {act, render, screen, fireEvent} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {AppShell} from './AppShell';
+import {Card} from '../Card/Card';
+import {Section} from '../Section/Section';
+import {LayoutAreaContext} from '../Layout/LayoutAreaContext';
+import {
+ DEFAULT_LAYOUT_SLOTS,
+ LayoutSlotsContext,
+} from '../Layout/LayoutSlotsContext';
+import {Layout} from '../Layout/Layout';
+import {LayoutHeader} from '../Layout/LayoutHeader';
import {InternationalizationProvider} from '../i18n';
import {MobileNav} from '../MobileNav';
import {SideNav, SideNavItem, SideNavSection} from '../SideNav';
@@ -1347,3 +1357,158 @@ describe('AppShell main keyboard access', () => {
expect(main).toHaveAttribute('tabindex', '-1');
});
});
+
+describe('AppShell layout root (FR18)', () => {
+ // A custom property set to `initial` reads back as `initial`; an empty
+ // value would mean the root declares nothing.
+ const CLEARED_READBACK = ['initial'];
+
+ function shell(testId: string) {
+ return (
+ <AppShell
+ data-testid={testId}
+ contentPadding={6}
+ topNav={
+ <TopNav label="Main" heading={<TopNavHeading heading="App" />} />
+ }
+ sideNav={
+ <SideNav>
+ <SideNavSection title="Main" isHeaderHidden>
+ <SideNavItem label="Dashboard" href="#" isSelected />
+ </SideNavSection>
+ </SideNav>
+ }>
+ {/* A page Layout of the app's own: its header takes the divider
+ default of the nearest Layout that sets one. */}
+ <Layout
+ header={<LayoutHeader>Page header</LayoutHeader>}
+ content={<p>Page content</p>}
+ />
+ </AppShell>
+ );
+ }
+
+ /** The shell's markup without its generated ids, for comparing two renders. */
+ function markup(testId: string): string {
+ const root = screen.getByTestId(testId);
+ return root.outerHTML
+ .replaceAll(testId, 'shell')
+ .replace(/(id|for|aria-[a-z]+|href)="[^"]*"/g, '$1=""');
+ }
+
+ it('stops the container padding, Layout values and height cap of a padded host at its root', () => {
+ render(<Card padding={3}>{shell('shell')}</Card>);
+ const computed = getComputedStyle(screen.getByTestId('shell'));
+ for (const edge of [
+ 'inline-start',
+ 'inline-end',
+ 'block-start',
+ 'block-end',
+ ]) {
+ expect(
+ computed.getPropertyValue(`--container-padding-${edge}`),
+ edge,
+ ).toBe('0px');
+ }
+ for (const name of [
+ '--layout-padding-outer-x',
+ '--layout-padding-outer-y',
+ '--layout-padding-own-outer-x',
+ '--layout-padding-own-outer-y',
+ '--layout-padding-inner-x',
+ '--layout-padding-inner-y',
+ '--layout-content-width',
+ '--layout-alignment-width',
+ '--_layout-flush-block-start',
+ '--_layout-flush-block-end',
+ '--_section-padding-propagated',
+ '--container-max-height',
+ ]) {
+ expect(CLEARED_READBACK, name).toContain(computed.getPropertyValue(name));
+ }
+ });
+
+ it('renders the same shell inside a padded Card and inside a Layout as at the page root', () => {
+ const {unmount} = render(shell('shell'));
+ const atRoot = markup('shell');
+ unmount();
+
+ const inCard = render(<Card padding={3}>{shell('shell')}</Card>);
+ expect(markup('shell')).toBe(atRoot);
+ inCard.unmount();
+
+ render(
+ <Layout
+ padding={4}
+ defaultHasDividers
+ header={<LayoutHeader>Outer header</LayoutHeader>}
+ content={shell('shell')}
+ />,
+ );
+ expect(markup('shell')).toBe(atRoot);
+ });
+
+ it('stops an enclosing divider default for every child of the root, the mobile nav node too', () => {
+ render(
+ <Layout
+ defaultHasDividers
+ content={
+ <AppShell
+ data-testid="shell"
+ mobileNav={
+ <LayoutHeader data-testid="mobile-header">Menu</LayoutHeader>
+ }>
+ <p>Page content</p>
+ </AppShell>
+ }
+ />,
+ );
+ expect(screen.getByTestId('mobile-header')).not.toHaveAttribute(
+ 'data-divider',
+ );
+ });
+
+ it('resets the Layout area and slot contexts for every child of the root', () => {
+ let seen: unknown = 'unrendered';
+ function Probe() {
+ seen = {area: use(LayoutAreaContext), slots: use(LayoutSlotsContext)};
+ return null;
+ }
+ render(
+ <Layout
+ header={<p>Outer header</p>}
+ start={<p>Outer start</p>}
+ content={
+ <AppShell mobileNav={<Probe />}>
+ <p>Page content</p>
+ </AppShell>
+ }
+ />,
+ );
+ // Inside the outer Layout's content area the probe would read area
+ // 'content' and the outer header and start slots; at the shell's root
+ // both are back to their defaults.
+ expect(seen).toEqual({area: null, slots: DEFAULT_LAYOUT_SLOTS});
+ });
+
+ it('keeps the caller style and a Section host out of each other', () => {
+ render(
+ <Section padding={6}>
+ <AppShell
+ data-testid="shell"
+ style={{['--container-padding-inline-start' as string]: '8px'}}>
+ <p>Page content</p>
+ </AppShell>
+ </Section>,
+ );
+ const computed = getComputedStyle(screen.getByTestId('shell'));
+ // The Section's propagated padding stops at the root...
+ expect(CLEARED_READBACK).toContain(
+ computed.getPropertyValue('--_section-padding-propagated'),
+ );
+ // ...and the caller's own style still applies after the reset (FR15).
+ expect(computed.getPropertyValue('--container-padding-inline-start')).toBe(
+ '8px',
+ );
+ });
+});
diff --git a/packages/core/src/AppShell/AppShell.tsx b/packages/core/src/AppShell/AppShell.tsx
index 58924e4648..ccce8fdff3 100644
--- a/packages/core/src/AppShell/AppShell.tsx
+++ b/packages/core/src/AppShell/AppShell.tsx
@@ -43,6 +43,13 @@ import {Layout} from '../Layout/Layout';
import {LayoutHeader} from '../Layout/LayoutHeader';
import {LayoutPanel} from '../Layout/LayoutPanel';
import {LayoutContent} from '../Layout/LayoutContent';
+import {LayoutAreaContext} from '../Layout/LayoutAreaContext';
+import {LayoutDividerContext} from '../Layout/LayoutDividerContext';
+import {
+ DEFAULT_LAYOUT_SLOTS,
+ LayoutSlotsContext,
+} from '../Layout/LayoutSlotsContext';
+import {layoutReset} from '../Layout/layoutReset';
import {MobileNavToggle} from '../MobileNav/MobileNavToggle';
import {MAX_CLOSE_DELAY_MS as MOBILE_NAV_MAX_CLOSE_DELAY_MS} from '../MobileNav/MobileNav';
import {SideNavRenderContext} from '../SideNav/SideNavRenderContext';
@@ -1249,6 +1256,9 @@ export function AppShell({
themeProps('app-shell', {variant}),
stylex.props(
styles.root,
+ // A layout root (FR18): nothing an ancestor Layout, Card or
+ // Section publishes reaches the shell (component:Layout FR8).
+ layoutReset,
variant === 'wash'
? styles.variantWash
: variant === 'surface'
@@ -1262,55 +1272,64 @@ export function AppShell({
className,
style,
)}>
- {/* Skip-to-content link */}
- <a
- href={`#${MAIN_CONTENT_ID}`}
- onClick={handleSkipLinkClick}
- {...focusOutlineProps.focusVisible(styles.skipLink)}
- data-testid="skip-to-content">
- {t('@astryx.appShell.skipToContent')}
- </a>
-
- <Layout
- height={height}
- padding={0}
- header={
- <>
- {headerContent}
- {autoMobileTopBar}
- </>
- }
- start={sideNavContent}
- content={mainContent}
- />
-
- {/* Mobile nav — always mounted below breakpoint via Activity so DOM
+ {/* The Layout area, slot and divider defaults an ancestor Layout
+ provides stop at the root too, for every child (FR18). */}
+ <LayoutAreaContext value={null}>
+ <LayoutSlotsContext value={DEFAULT_LAYOUT_SLOTS}>
+ <LayoutDividerContext value={null}>
+ {/* Skip-to-content link */}
+ <a
+ href={`#${MAIN_CONTENT_ID}`}
+ onClick={handleSkipLinkClick}
+ {...focusOutlineProps.focusVisible(styles.skipLink)}
+ data-testid="skip-to-content">
+ {t('@astryx.appShell.skipToContent')}
+ </a>
+
+ <Layout
+ height={height}
+ padding={0}
+ header={
+ <>
+ {headerContent}
+ {autoMobileTopBar}
+ </>
+ }
+ start={sideNavContent}
+ content={mainContent}
+ />
+
+ {/* Mobile nav — always mounted below breakpoint via Activity so DOM
presence detection works. Hidden until the drawer opens. */}
- {shouldRenderMobileNavReactNode && mobileNavReactNode}
- {shouldRenderConfigContent && mobileNavConfigContent}
- {isBelowBreakpoint &&
- !mobileNavDisabled &&
- mobileNavReactNode == null &&
- !mobileNavConfigContent && (
- <ActivityWrapper
- mode={isMobileNavActivityVisible ? 'visible' : 'hidden'}>
- {/* SideNav drawer — always mounted so presence detection works.
+ {shouldRenderMobileNavReactNode && mobileNavReactNode}
+ {shouldRenderConfigContent && mobileNavConfigContent}
+ {isBelowBreakpoint &&
+ !mobileNavDisabled &&
+ mobileNavReactNode == null &&
+ !mobileNavConfigContent && (
+ <ActivityWrapper
+ mode={isMobileNavActivityVisible ? 'visible' : 'hidden'}>
+ {/* SideNav drawer — always mounted so presence detection works.
Hidden when TopNav owns the drawer (combined mode passes
sideNav via TopNav's mobile content context instead). */}
- {hasSideNav && !hasTopNav && (
- <SideNavRenderContext value="drawer">
- {sideNav}
- </SideNavRenderContext>
- )}
- {hasTopNav && (
- <TopNavMobileContentContext value={drawerMobileContentValue}>
- <TopNavRenderContext value="drawer">
- {topNav}
- </TopNavRenderContext>
- </TopNavMobileContentContext>
- )}
- </ActivityWrapper>
- )}
+ {hasSideNav && !hasTopNav && (
+ <SideNavRenderContext value="drawer">
+ {sideNav}
+ </SideNavRenderContext>
+ )}
+ {hasTopNav && (
+ <TopNavMobileContentContext
+ value={drawerMobileContentValue}>
+ <TopNavRenderContext value="drawer">
+ {topNav}
+ </TopNavRenderContext>
+ </TopNavMobileContentContext>
+ )}
+ </ActivityWrapper>
+ )}
+ </LayoutDividerContext>
+ </LayoutSlotsContext>
+ </LayoutAreaContext>
</div>
</AppShellMobileContext>
);
diff --git a/packages/core/src/AppShell/__tests__/AppShellLayoutRoot.interaction.browser.spec.ts b/packages/core/src/AppShell/__tests__/AppShellLayoutRoot.interaction.browser.spec.ts
new file mode 100644
index 0000000000..3ac15a2631
--- /dev/null
+++ b/packages/core/src/AppShell/__tests__/AppShellLayoutRoot.interaction.browser.spec.ts
@@ -0,0 +1,108 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file AppShellLayoutRoot.interaction.browser.spec.ts
+ * @input The `Core/AppShell` Inside Layout Hosts story in a built Storybook,
+ * its `host` arg placing one shell at the page root, in a padded Card that
+ * clips overflow, in an outer Layout's content area, or in a Section with
+ * explicit padding.
+ * @output Real-browser geometry evidence for `component:AppShell` FR18: inside
+ * a padded Card, a Layout or a Section, the shell's internal Layout stays inside its
+ * root (no overhang), and its header logo, side region and main region sit
+ * at the same offsets from the shell's root as at the page root, at desktop
+ * and phone widths.
+ * @position Cross-browser proof; jsdom has no layout, so AppShell.test.tsx
+ * can only compare the reset values and markup.
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer | undefined;
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+const STORY = 'core-appshell--inside-layout-hosts';
+
+interface ShellGeometry {
+ overhang: {left: number; top: number; right: number; bottom: number};
+ offsets: Record<string, {left: number; top: number} | null>;
+}
+
+/** Offsets from the shell's root of its regions, and its Layout's overhang. */
+async function measure(page: Page, host: string): Promise<ShellGeometry> {
+ await page.goto(
+ `${storybook?.origin}/iframe.html?id=${STORY}&viewMode=story&args=host:${host}`,
+ );
+ await expect(page.getByTestId('shell')).toBeVisible();
+ return page.evaluate(() => {
+ const shell = document.querySelector<HTMLElement>('[data-testid="shell"]');
+ if (shell == null) {
+ throw new Error('no shell');
+ }
+ const root = shell.getBoundingClientRect();
+ const layout = shell.querySelector<HTMLElement>('.astryx-layout');
+ if (layout == null) {
+ throw new Error('no layout in the shell');
+ }
+ const inner = layout.getBoundingClientRect();
+ const offset = (element: Element | null) => {
+ if (element == null) {
+ return null;
+ }
+ const rect = element.getBoundingClientRect();
+ return {
+ left: Math.round(rect.left - root.left),
+ top: Math.round(rect.top - root.top),
+ };
+ };
+ return {
+ overhang: {
+ left: Math.round(root.left - inner.left),
+ top: Math.round(root.top - inner.top),
+ right: Math.round(inner.right - root.right),
+ bottom: Math.round(inner.bottom - root.bottom),
+ },
+ offsets: {
+ logo: offset(shell.querySelector('.astryx-nav-icon')),
+ side: offset(shell.querySelector('.astryx-side-nav')),
+ main: offset(shell.querySelector('[role="main"]')),
+ },
+ };
+ });
+}
+
+for (const viewport of [
+ {width: 1280, height: 1400},
+ {width: 390, height: 1400},
+]) {
+ test(`lays out inside a padded Card and a Layout as at the page root at ${viewport.width}px (FR18)`, async ({
+ page,
+ }) => {
+ await page.setViewportSize(viewport);
+ const atRoot = await measure(page, 'root');
+ expect(atRoot.overhang, 'page root').toEqual({
+ left: 0,
+ top: 0,
+ right: 0,
+ bottom: 0,
+ });
+ for (const host of ['card', 'layout', 'section']) {
+ const inHost = await measure(page, host);
+ expect(inHost.overhang, `${host}: Layout overhang`).toEqual(
+ atRoot.overhang,
+ );
+ expect(inHost.offsets, `${host}: region offsets`).toEqual(atRoot.offsets);
+ }
+ });
+}
diff --git a/packages/core/src/Layout/LayoutSlotsContext.ts b/packages/core/src/Layout/LayoutSlotsContext.ts
index d728fd8f04..d6553a987d 100644
--- a/packages/core/src/Layout/LayoutSlotsContext.ts
+++ b/packages/core/src/Layout/LayoutSlotsContext.ts
@@ -34,7 +34,8 @@ export interface LayoutSlots {
/**
* Default slot state - no slots filled.
*/
-const defaultSlots: LayoutSlots = {
+/** The slots outside any Layout: none rendered (a layout root resets to it). */
+export const DEFAULT_LAYOUT_SLOTS: LayoutSlots = {
hasHeader: false,
hasFooter: false,
hasStart: false,
@@ -46,5 +47,6 @@ const defaultSlots: LayoutSlots = {
* Content area components use this to determine if they are at an edge
* (for applying outer padding).
*/
-export const LayoutSlotsContext = createContext<LayoutSlots>(defaultSlots);
+export const LayoutSlotsContext =
+ createContext<LayoutSlots>(DEFAULT_LAYOUT_SLOTS);
LayoutSlotsContext.displayName = 'LayoutSlotsContext';
diff --git a/packages/core/src/Layout/layoutReset.test.tsx b/packages/core/src/Layout/layoutReset.test.tsx
new file mode 100644
index 0000000000..9821a00daa
--- /dev/null
+++ b/packages/core/src/Layout/layoutReset.test.tsx
@@ -0,0 +1,92 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layoutReset.test.tsx
+ * @input Layout's and Section's source files, and `layoutReset` applied to an
+ * element inside a padded Section.
+ * @output Proof that the reset covers every layout custom property Layout
+ * writes (`component:Layout` FR8): a new property fails here until the
+ * reset stops it too.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
+import {describe, expect, it} from 'vitest';
+import {layoutReset} from './layoutReset';
+import {Section} from '../Section/Section';
+
+const SRC = path.resolve(__dirname, '..');
+
+/** The directories whose components publish layout custom properties. */
+const WRITERS = ['Layout', 'Section'];
+
+/** Every layout custom property written as a style key in a writer's source. */
+function writtenLayoutProperties(): string[] {
+ const names = new Set<string>();
+ for (const dir of WRITERS) {
+ for (const file of fs.readdirSync(path.join(SRC, dir), {recursive: true})) {
+ const name = String(file);
+ if (!/\.tsx?$/.test(name) || /\.(test|spec)\./.test(name)) {
+ continue;
+ }
+ const source = fs.readFileSync(path.join(SRC, dir, name), 'utf8');
+ for (const match of source.matchAll(
+ /['"](--(?:layout|_layout|container|_section)[\w-]*)['"]\s*:/g,
+ )) {
+ names.add(match[1]);
+ }
+ }
+ }
+ return [...names].sort();
+}
+
+/** The custom properties `layoutReset` sets, as its readers see them. */
+const RESET_VALUES: Record<string, string[]> = {
+ '0px': [
+ '--container-padding-inline-start',
+ '--container-padding-inline-end',
+ '--container-padding-block-start',
+ '--container-padding-block-end',
+ ],
+ initial: [
+ '--layout-padding-outer-x',
+ '--layout-padding-outer-y',
+ '--layout-padding-own-outer-x',
+ '--layout-padding-own-outer-y',
+ '--layout-padding-inner-x',
+ '--layout-padding-inner-y',
+ '--layout-content-width',
+ '--layout-alignment-width',
+ '--_layout-flush-block-start',
+ '--_layout-flush-block-end',
+ '--_section-padding-propagated',
+ '--container-max-height',
+ ],
+};
+const RESET_PROPERTIES = Object.values(RESET_VALUES).flat().sort();
+
+describe('layoutReset (component:Layout FR8)', () => {
+ it('covers every layout custom property Layout and Section write', () => {
+ const written = writtenLayoutProperties();
+ expect(written.length).toBeGreaterThan(0);
+ expect(RESET_PROPERTIES).toEqual(written);
+ });
+
+ it('stops each of them at the element it is applied to', () => {
+ render(
+ <Section padding={10}>
+ <div data-testid="root" {...stylex.props(layoutReset)} />
+ </Section>,
+ );
+ const computed = getComputedStyle(screen.getByTestId('root'));
+ for (const name of RESET_VALUES['0px']) {
+ expect(computed.getPropertyValue(name), name).toBe('0px');
+ }
+ for (const name of RESET_VALUES.initial) {
+ // An empty value would mean the reset declares nothing.
+ expect(computed.getPropertyValue(name), name).toBe('initial');
+ }
+ });
+});
diff --git a/packages/core/src/Layout/layoutReset.ts b/packages/core/src/Layout/layoutReset.ts
new file mode 100644
index 0000000000..2fb3472fa1
--- /dev/null
+++ b/packages/core/src/Layout/layoutReset.ts
@@ -0,0 +1,45 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file layoutReset.ts
+ * @input The layout custom properties Layout, its regions, Section and the
+ * container styles publish to their descendants.
+ * @output `layoutReset`: the StyleX styles that stop every one of them at an
+ * element, so what renders inside lays out as it does at a page root.
+ * @position Layout owns the reset (`component:Layout` FR8). A layout root
+ * applies it, as AppShell does at its root (`component:AppShell` FR18).
+ * Internal: no package entry exports it. `layoutReset.test.tsx` fails when
+ * Layout writes a custom property this reset does not cover.
+ *
+ * SYNC: the docsite's example root composes `overlayPaddingReset` and
+ * mirrors the rest of this list (apps/docsite/src/components/component-detail/
+ * ExampleBlock.tsx); apps/docsite/src/__tests__/example-layout-root.test.ts
+ * fails when they differ.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {overlayPaddingReset} from './padding.stylex';
+
+const resetBeyondOverlays = stylex.create({
+ root: {
+ // Added by descendants, beyond what an overlay root resets: each reader
+ // falls back to its own default.
+ '--layout-content-width': 'initial',
+ '--layout-alignment-width': 'initial',
+ '--_layout-flush-block-start': 'initial',
+ '--_layout-flush-block-end': 'initial',
+ '--container-max-height': 'initial',
+ },
+});
+
+/**
+ * The full layout reset, for `stylex.props(...)`: `overlayPaddingReset` (the
+ * published container padding to `0px`; Layout insets and Section padding
+ * propagation to `initial`) plus the Layout widths, flush values and height
+ * cap. The shared declarations keep one owner, so a fix to either reaches
+ * every root that applies them.
+ */
+export const layoutReset = [
+ overlayPaddingReset.reset,
+ resetBeyondOverlays.root,
+] as const;