An open source design system that's fully customizable and agent ready
TypeScript
[Component Audit] Layout: a region hidden with && lays out like an omitted one (#10500)
Cindy Zhang227855776a98
diff --git a/.changeset/layout-closed-slot-is-empty.md b/.changeset/layout-closed-slot-is-empty.mdnew file mode 100644index 0000000000..eb738079bf--- /dev/null+++ b/.changeset/layout-closed-slot-is-empty.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] `Layout`: a `false`, `true`, or empty-string slot, such as `false` from `isOpen && <LayoutPanel />`, now counts as empty. The neighbouring regions move out to the layout edge, the same as when the slot is omitted, and with `contentWidth` a closed side panel no longer stops the content area at the content-width frame. The docs now list `children` and `ref`, show how to hide a region, and say that landmark roles go on the region components.++@cixzhangdiff --git a/apps/storybook/stories/Layout.stories.tsx b/apps/storybook/stories/Layout.stories.tsxindex 83d4007a13..49f870352a 100644--- a/apps/storybook/stories/Layout.stories.tsx+++ b/apps/storybook/stories/Layout.stories.tsx@@ -763,6 +763,116 @@ export const ContentOnly: Story = {),};+interface ClosedRegionsArgs {+ isOpen: boolean;+}++/**+ * A region hidden with `isOpen && <LayoutHeader />` leaves `false` in its+ * slot. The closed column must match the column that omits the slots: both+ * set `padding={6}`, so the outer inset differs from the inner one. With+ * `contentWidth`, a closed end panel must give the no-panel composition.+ */+export const ClosedRegions = {+ name: 'Closed Regions',+ args: {isOpen: false},+ argTypes: {+ isOpen: {+ control: 'boolean',+ description: 'Open the regions that the closed examples hide',+ },+ },+ render: ({isOpen}: ClosedRegionsArgs) => (+ <VStack gap={6} xstyle={styles.storySection}>+ <HStack gap={4}>+ <VStack gap={2}>+ <p {...stylex.props(styles.subheading)}>Slots omitted, padding=6</p>+ <Card width={300} height={220} data-closed-region="omitted">+ <Layout+ padding={6}+ content={+ <LayoutContent>+ <p {...stylex.props(styles.bodyText)}>Content area.</p>+ </LayoutContent>+ }+ />+ </Card>+ </VStack>+ <VStack gap={2}>+ <p {...stylex.props(styles.subheading)}>+ {isOpen ? 'Regions open' : 'Regions closed'}, padding=6+ </p>+ <Card width={300} height={220} data-closed-region="closed">+ <Layout+ padding={6}+ header={+ isOpen && (+ <LayoutHeader hasDivider>+ <h3 {...stylex.props(styles.heading)}>Header</h3>+ </LayoutHeader>+ )+ }+ start={+ isOpen && (+ <LayoutPanel width={100} hasDivider>+ <NavItem active>Nav</NavItem>+ </LayoutPanel>+ )+ }+ content={+ <LayoutContent>+ <p {...stylex.props(styles.bodyText)}>Content area.</p>+ </LayoutContent>+ }+ footer={+ isOpen && (+ <LayoutFooter hasDivider>+ <p {...stylex.props(styles.bodyText)}>Footer</p>+ </LayoutFooter>+ )+ }+ />+ </Card>+ </VStack>+ </HStack>+ <VStack gap={2}>+ <p {...stylex.props(styles.subheading)}>+ contentWidth=400 with the end panel closed+ </p>+ <div+ data-closed-region="content-width"+ {...stylex.props(+ styles.cwContainer,+ styles.cwContainer640,+ styles.cwContainerMatrix,+ )}>+ <Layout+ contentWidth={400}+ header={+ <LayoutHeader hasDivider>+ <HStack hAlign="between">+ <span data-header-edge="start">Header start</span>+ <span data-header-edge="end">Header end</span>+ </HStack>+ </LayoutHeader>+ }+ content={+ <ScrollbarProbeContent id="closed-end" label="Closed end panel" />+ }+ end={+ isOpen && (+ <LayoutPanel width={120} hasDivider>+ <p {...stylex.props(styles.bodyText)}>Details</p>+ </LayoutPanel>+ )+ }+ />+ </div>+ </VStack>+ </VStack>+ ),+};+export const ThemedLayout: Story = {name: 'Themed Layout (Neutral vs Stone)',render: () => (diff --git a/packages/cli/test/core-prop-docs.known-drift.json b/packages/cli/test/core-prop-docs.known-drift.jsonindex 0342573826..97c64caaed 100644--- a/packages/cli/test/core-prop-docs.known-drift.json+++ b/packages/cli/test/core-prop-docs.known-drift.json@@ -21,7 +21,6 @@"src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs DropdownMenuCheckboxItem.value required_mismatch","src/FieldStatus/FieldStatus.doc.mjs FieldStatus.variant type_mismatch","src/HoverCard/HoverCard.doc.mjs HoverCard.children required_mismatch",- "src/Layout/Layout.doc.mjs Layout.children not_in_doc","src/Layout/LayoutFooter.doc.mjs LayoutFooter.padding not_in_doc","src/Layout/LayoutHeader.doc.mjs LayoutHeader.padding not_in_doc","src/Link/Link.doc.mjs Link.type not_in_doc",diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjsindex 7fc6484c34..cdb722175f 100644--- a/packages/core/src/Layout/Layout.doc.mjs+++ b/packages/core/src/Layout/Layout.doc.mjs@@ -144,6 +144,17 @@ export const docs = {description:"Padding at the layout's outer edges using the spacing scale. Applies to this Layout's own header, footer, panels, and content. A nested Layout does not inherit it: without `padding`, its regions use the enclosing Card, Section, or Dialog padding, or the default inset (spacing 4). That keeps a page Layout inside AppShell inset even though AppShell's own regions are full bleed.",},+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Shorthand for the content slot: `<Layout>{main}</Layout>` is the same as `<Layout content={main} />`. When both are given, `content` wins.',+ },+ {+ name: 'ref',+ type: 'React.Ref<HTMLDivElement>',+ description: 'Ref forwarded to the root layout element.',+ },{name: 'defaultHasDividers',type: 'boolean',@@ -165,6 +176,8 @@ export const docs = {bestPractices: [{ guidance: true, description: 'Use Layout when content needs named header, start, content, end, or footer regions.' },{ guidance: true, description: 'Use HStack and VStack for simple directional stacking within a content area.' },+ { guidance: true, description: 'Hide a region by passing `false`, `null`, or `undefined` to its slot, for example `isOpen && <LayoutPanel />`. The slot counts as empty, so the neighbouring regions move out to the layout edge.' },+ { guidance: true, description: 'Give a region a landmark role and label on the region component when it is a page landmark, for example `<LayoutPanel role="navigation" label="Sections">`. Layout adds no role or name.' },{ guidance: false, description: 'Use Layout for simple stacking layouts; use HStack or VStack instead.' },{ guidance: false, description: 'Use Layout as the page shell or for app-wide navigation; use AppShell for that responsibility.' },],@@ -230,6 +243,8 @@ export const docsZh = {bestPractices: [{ guidance: true, description: 'Use Layout when content needs named header, start, content, end, or footer regions.' },{ guidance: true, description: 'Use HStack and VStack for simple directional stacking within a content area.' },+ { guidance: true, description: 'Hide a region by passing `false`, `null`, or `undefined` to its slot, for example `isOpen && <LayoutPanel />`. The slot counts as empty, so the neighbouring regions move out to the layout edge.' },+ { guidance: true, description: 'Give a region a landmark role and label on the region component when it is a page landmark, for example `<LayoutPanel role="navigation" label="Sections">`. Layout adds no role or name.' },{ guidance: false, description: 'Use Layout for simple stacking layouts; use HStack or VStack instead.' },{ guidance: false, description: 'Use Layout as the page shell or for app-wide navigation; use AppShell for that responsibility.' },],@@ -246,6 +261,8 @@ export const docsDense = {bestPractices: [{ guidance: true, description: 'Use Layout when content needs named header, start, content, end, or footer regions.' },{ guidance: true, description: 'Use HStack and VStack for simple directional stacking within a content area.' },+ { guidance: true, description: 'Hide a region by passing `false`, `null`, or `undefined` to its slot, for example `isOpen && <LayoutPanel />`. The slot counts as empty, so the neighbouring regions move out to the layout edge.' },+ { guidance: true, description: 'Give a region a landmark role and label on the region component when it is a page landmark, for example `<LayoutPanel role="navigation" label="Sections">`. Layout adds no role or name.' },{ guidance: false, description: 'Use Layout for simple stacking layouts; use HStack or VStack instead.' },{ guidance: false, description: 'Use Layout as the page shell or for app-wide navigation; use AppShell for that responsibility.' },],diff --git a/packages/core/src/Layout/Layout.test.tsx b/packages/core/src/Layout/Layout.test.tsxindex 6516d2f3ed..1848aecabe 100644--- a/packages/core/src/Layout/Layout.test.tsx+++ b/packages/core/src/Layout/Layout.test.tsx@@ -10,12 +10,13 @@* SYNC: When Layout.tsx changes, update tests to match new behavior*/-import {describe, it, expect} from 'vitest';-import {render, screen} from '@testing-library/react';+import {describe, it, expect, vi} from 'vitest';+import {fireEvent, render, screen} from '@testing-library/react';import {use, createRef} from 'react';import {Layout} from './Layout';import {LayoutHeader} from './LayoutHeader';import {LayoutFooter} from './LayoutFooter';+import {Dialog} from '../Dialog/Dialog';import {LayoutAreaContext} from './LayoutAreaContext';import {LayoutSlotsContext} from './LayoutSlotsContext';@@ -141,6 +142,26 @@ describe('Layout', () => {});});+ it('reports a slot that renders nothing as empty', () => {+ // `false` is what `isOpen && <LayoutHeader />` gives when closed.+ render(+ <Layout+ header={false}+ footer={true}+ start=""+ end={false}+ content={<SlotsProbe />}+ />,+ );+ const slots = JSON.parse(screen.getByTestId('slots').textContent ?? '{}');+ expect(slots).toEqual({+ hasHeader: false,+ hasFooter: false,+ hasStart: false,+ hasEnd: false,+ });+ });+it('reports every slot filled', () => {render(<Layout@@ -219,6 +240,46 @@ describe('Layout', () => {).toBeNull();});+ it('a nested Layout without defaultHasDividers keeps its parent default', () => {+ const {container} = render(+ <Layout+ defaultHasDividers+ content={+ <Layout+ header={<LayoutHeader>Nested</LayoutHeader>}+ content={<div>c</div>}+ />+ }+ />,+ );+ expect(+ container.querySelector('.astryx-layout-header[data-divider]'),+ ).not.toBeNull();+ });++ it('stops the default at a layer boundary', () => {+ render(+ <Layout+ defaultHasDividers+ content={+ <Dialog+ isOpen+ isInline+ aria-label="Settings"+ onOpenChange={() => {}}>+ <Layout+ header={<LayoutHeader>In dialog</LayoutHeader>}+ content={<div>c</div>}+ />+ </Dialog>+ }+ />,+ );+ expect(+ screen.getByText('In dialog').closest('.astryx-layout-header'),+ ).not.toHaveAttribute('data-divider');+ });+it('an explicit hasDivider={false} on a header overrides the context default', () => {const {container} = render(<Layout@@ -365,6 +426,15 @@ describe('Layout', () => {expect(el).toHaveAttribute('data-zone', 'admin');});+ it('forwards event handlers to the root element', () => {+ const onClick = vi.fn();+ const {container} = render(+ <Layout onClick={onClick} content={<div>c</div>} />,+ );+ fireEvent.click(root(container));+ expect(onClick).toHaveBeenCalledTimes(1);+ });+it('keeps component-owned theme metadata over a colliding pass-through', () => {const {container} = render(<Layout height="fill" data-height="auto" content={<div>c</div>} />,diff --git a/packages/core/src/Layout/Layout.tsx b/packages/core/src/Layout/Layout.tsxindex b6b95f6306..7d5d1d56af 100644--- a/packages/core/src/Layout/Layout.tsx+++ b/packages/core/src/Layout/Layout.tsx@@ -4,7 +4,7 @@/*** @file Layout.tsx- * @input Uses React, stack/stackItem utilities, LayoutAreaContext, LayoutSlotsContext+ * @input Uses React, stack/stackItem utilities, isRenderable, LayoutAreaContext, LayoutSlotsContext* @output Exports Layout component and LayoutProps, LayoutHeight types* @position General five-slot layout primitive for arranging header, start, content, end, and footer regions.* Building a page area with a side panel? Use Layout with start/end slots.@@ -25,6 +25,7 @@ import {LayoutDividerContext} from './LayoutDividerContext';import {stack} from '../Stack/stack.stylex';import {stackItem} from '../Stack/stackItem.stylex';import {mergeProps} from '../utils/mergeProps';+import {isRenderable} from '../utils/isRenderable';import {layoutFooterMarker, layoutHeaderMarker} from './layoutEdges.stylex';import type {BaseProps} from '../BaseProps';import type {SizeValue, SpacingStep} from '../utils/types';@@ -366,11 +367,12 @@ export function Layout({[defaultHasDividers],);- // Memoize slots info to avoid unnecessary re-renders- const hasHeader = header != null;- const hasFooter = footer != null;- const hasStart = start != null;- const hasEnd = end != null;+ // A slot that renders nothing, such as `false` from `isOpen && <LayoutHeader />`,+ // is absent, so its neighbours take the outer inset on that side.+ const hasHeader = isRenderable(header);+ const hasFooter = isRenderable(footer);+ const hasStart = isRenderable(start);+ const hasEnd = isRenderable(end);const hasBothPanels = hasStart && hasEnd;const hasSinglePanel = hasStart !== hasEnd;const usesInternalContentWidth =diff --git a/packages/core/src/Layout/__tests__/LayoutAudit.a11y.chromium.spec.ts b/packages/core/src/Layout/__tests__/LayoutAudit.a11y.chromium.spec.tsnew file mode 100644index 0000000000..6ce4053f8b--- /dev/null+++ b/packages/core/src/Layout/__tests__/LayoutAudit.a11y.chromium.spec.ts@@ -0,0 +1,615 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+// @pr-a11y audit Layout++/**+ * @file LayoutAudit.a11y.chromium.spec.ts+ * @input Exact-head Core/Layout stories across themes, modes, direction, and width+ * @output Screenshots and fail-closed sensor receipts for the Layout whole-component audit+ * @position Component-owned Night Watch browser evidence; CI runs it only for a Layout audit pull request+ */++import {createHash} from 'node:crypto';+import {execFileSync} from 'node:child_process';+import * as fs from 'node:fs';+import * as path from 'node:path';+import {expect, test, type Page} from '@astryxdesign/a11y-spec/playwright';+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';+import {+ DEFAULT_STORYBOOK_DIR,+ serveStorybook,+ type StaticServer,+} from '@astryxdesign/a11y-spec/storybook';++const OUTPUT = path.resolve('layout-audit-evidence');+const WIDE = {width: 1280, height: 800};+const TALL = {width: 1280, height: 1400};+const NARROW = {width: 320, height: 900};++type Mode = 'light' | 'dark';+type Theme = 'neutral' | 'butter';+type Direction = 'ltr' | 'rtl';+type Story =+ | 'basic-card'+ | 'with-sidebar'+ | 'dual-panels'+ | 'no-dividers'+ | 'full-bleed-content'+ | 'content-only'+ | 'closed-regions'+ | 'content-width-scrollbar-placement'+ | 'nested-in-app-shell';++type AuditCase = {+ key: string;+ story: Story;+ mode: Mode;+ theme: Theme;+ direction: Direction;+ viewport: {width: number; height: number};+};++type AuditReceipt = {+ passed: boolean;+ expected: Record<string, unknown>;+ failures: string[];+};++// The number of Layout roots each story renders, so a story that stops+// rendering one fails instead of passing with nothing to check.+const LAYOUTS: Record<Story, number> = {+ 'basic-card': 1,+ 'with-sidebar': 1,+ 'dual-panels': 1,+ 'no-dividers': 1,+ 'full-bleed-content': 1,+ 'content-only': 1,+ 'closed-regions': 3,+ 'content-width-scrollbar-placement': 4,+ 'nested-in-app-shell': 3,+};++const cases: AuditCase[] = [];+function add(+ story: Story,+ options: {+ theme?: Theme;+ direction?: Direction;+ modes?: Mode[];+ viewport?: {width: number; height: number};+ suffix?: string;+ } = {},+) {+ const theme = options.theme ?? 'neutral';+ const direction = options.direction ?? 'ltr';+ for (const mode of options.modes ?? ['light', 'dark']) {+ const parts: string[] = [story, options.suffix ?? '', theme];+ if (direction === 'rtl') {+ parts.push('rtl');+ }+ cases.push({+ key: `${parts.filter(Boolean).join('-')}-${mode}`,+ story,+ mode,+ theme,+ direction,+ viewport: options.viewport ?? WIDE,+ });+ }+}++add('basic-card');+add('basic-card', {theme: 'butter', modes: ['light']});+add('with-sidebar');+add('with-sidebar', {direction: 'rtl', modes: ['light']});+add('dual-panels', {modes: ['light']});+add('dual-panels', {direction: 'rtl', modes: ['light']});+add('no-dividers', {modes: ['light']});+add('full-bleed-content', {modes: ['light']});+add('content-only', {modes: ['light']});+add('closed-regions');+add('closed-regions', {theme: 'butter', modes: ['light']});+add('closed-regions', {direction: 'rtl', modes: ['light']});+add('content-width-scrollbar-placement', {modes: ['light'], viewport: TALL});+add('nested-in-app-shell', {modes: ['light']});+add('nested-in-app-shell', {+ suffix: 'narrow',+ modes: ['light'],+ viewport: NARROW,+});++test.describe.configure({retries: 0});+let server: StaticServer;+let checkoutSha: string;+let storybookSha: string;++function storyUrl(item: AuditCase) {+ return `${server.origin}/iframe.html?id=core-layout--${item.story}&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme};direction:${item.direction}`;+}++async function settle(page: Page) {+ await holdMotionStill(page);+ await page.evaluate(async () => document.fonts.ready);+ await page.evaluate(+ async () =>+ new Promise<void>(resolve =>+ requestAnimationFrame(() => requestAnimationFrame(() => resolve())),+ ),+ );+ await page.waitForTimeout(40);+}++async function observe(page: Page) {+ return page.evaluate(() => {+ const round = (value: number) => Math.round(value * 10) / 10;+ const px = (value: string) => parseFloat(value) || 0;+ type Box = {+ left: number;+ top: number;+ right: number;+ bottom: number;+ width: number;+ height: number;+ };+ function box(element: Element): Box {+ const rect = element.getBoundingClientRect();+ return {+ left: round(rect.left),+ top: round(rect.top),+ right: round(rect.right),+ bottom: round(rect.bottom),+ width: round(rect.width),+ height: round(rect.height),+ };+ }+ function padding(element: Element) {+ const style = getComputedStyle(element);+ return {+ blockStart: px(style.paddingBlockStart),+ blockEnd: px(style.paddingBlockEnd),+ inlineStart: px(style.paddingInlineStart),+ inlineEnd: px(style.paddingInlineEnd),+ };+ }+ const EDGES = [+ 'inline-start',+ 'inline-end',+ 'block-start',+ 'block-end',+ ] as const;+ // Resolve each published padding to pixels in the element's own scope:+ // the custom property holds an unresolved length such as a rem value.+ function published(element: Element) {+ const values = EDGES.map(edge => {+ const probe = document.createElement('div');+ probe.style.cssText = `position:absolute;visibility:hidden;width:var(--container-padding-${edge}, 0px)`;+ element.appendChild(probe);+ const width = px(getComputedStyle(probe).width);+ probe.remove();+ return [edge, width];+ });+ return Object.fromEntries(values) as Record<+ (typeof EDGES)[number],+ number+ >;+ }+ const REGION_KINDS = ['header', 'panel', 'content', 'footer'] as const;+ function regionKind(element: Element) {+ return REGION_KINDS.find(kind =>+ element.classList.contains(`astryx-layout-${kind}`),+ );+ }+ function regionsOf(root: Element) {+ return Array.from(+ root.querySelectorAll(+ REGION_KINDS.map(kind => `.astryx-layout-${kind}`).join(','),+ ),+ ).filter(region => region.closest('.astryx-layout') === root);+ }++ const roots = Array.from(+ document.querySelectorAll('#storybook-root .astryx-layout'),+ );+ const layouts = roots.map(root => {+ const style = getComputedStyle(root);+ const inner = root.firstElementChild;+ return {+ role: root.getAttribute('role'),+ ariaLabel: root.getAttribute('aria-label'),+ ariaLabelledby: root.getAttribute('aria-labelledby'),+ height: root.getAttribute('data-height'),+ targets: Array.from(root.classList).filter(name =>+ name.startsWith('astryx-'),+ ),+ background: style.backgroundColor,+ direction: style.direction,+ box: box(root),+ margins: {+ 'inline-start': px(style.marginInlineStart),+ 'inline-end': px(style.marginInlineEnd),+ 'block-start': px(style.marginBlockStart),+ 'block-end': px(style.marginBlockEnd),+ },+ parentPublished: published(root.parentElement as Element),+ innerPublished: inner == null ? null : published(inner),+ frame: box(root.parentElement as Element),+ regions: regionsOf(root).map(region => ({+ kind: regionKind(region),+ box: box(region),+ })),+ };+ });++ function closedCase(name: string) {+ const host = document.querySelector(`[data-closed-region="${name}"]`);+ if (host == null) {+ return null;+ }+ const root = host.querySelector('.astryx-layout');+ const content = root?.querySelector('.astryx-layout-content');+ if (root == null || content == null) {+ return {found: false as const};+ }+ const hostBox = box(host);+ const contentBox = box(content);+ return {+ found: true as const,+ regionKinds: regionsOf(root).map(regionKind),+ rootBox: box(root),+ contentBox,+ contentOffset: {+ inlineStart: round(contentBox.left - hostBox.left),+ inlineEnd: round(hostBox.right - contentBox.right),+ blockStart: round(contentBox.top - hostBox.top),+ blockEnd: round(hostBox.bottom - contentBox.bottom),+ },+ contentPadding: padding(content),+ };+ }++ return {+ theme: document+ .querySelector('[data-astryx-theme]')+ ?.getAttribute('data-astryx-theme'),+ mode: document.documentElement.getAttribute('data-theme'),+ viewport: {width: innerWidth, height: innerHeight},+ dpr: devicePixelRatio,+ reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,+ fonts: document.fonts.status,+ storybookError:+ document.querySelector('.sb-show-errordisplay') != null ||+ document.body.classList.contains('sb-show-errordisplay'),+ documentOverflow: round(+ document.documentElement.scrollWidth - innerWidth,+ ),+ layouts,+ closed: {+ omitted: closedCase('omitted'),+ closed: closedCase('closed'),+ contentWidth: closedCase('content-width'),+ },+ };+ });+}++test.beforeAll(async () => {+ fs.mkdirSync(OUTPUT, {recursive: true});+ checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {+ encoding: 'utf8',+ }).trim();+ const expected = process.env.ASTRYX_HEAD_SHA;+ if (expected && expected !== checkoutSha) {+ throw new Error(+ `checkout ${checkoutSha} does not match expected head ${expected}`,+ );+ }+ server = await serveStorybook(+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,+ );+ const response = await fetch(`${server.origin}/astryx-build-sha.txt`);+ if (!response.ok) {+ throw new Error(`Storybook build has no SHA stamp (${response.status})`);+ }+ storybookSha = (await response.text()).trim();+ if (storybookSha !== checkoutSha) {+ throw new Error(+ `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,+ );+ }+});++test.afterAll(async () => {+ await server?.close();+});++for (const item of cases) {+ test(item.key, async ({browser}) => {+ const context = await browser.newContext({+ viewport: item.viewport,+ deviceScaleFactor: 2,+ colorScheme: item.mode,+ reducedMotion: 'reduce',+ });+ const page = await context.newPage();+ const pageErrors: string[] = [];+ page.on('pageerror', error => pageErrors.push(String(error)));+ await page.goto(storyUrl(item), {waitUntil: 'load'});+ await page.locator('#storybook-root .astryx-layout').first().waitFor();+ await settle(page);++ const first = await observe(page);+ await page.waitForTimeout(100);+ await settle(page);+ const observed = await observe(page);+ const geometryStable =+ JSON.stringify(first.layouts.map(layout => layout.box)) ===+ JSON.stringify(observed.layouts.map(layout => layout.box));++ const failures: string[] = [];+ const check = (condition: boolean, message: string) => {+ if (!condition) {+ failures.push(message);+ }+ };+ const near = (actual: number, expected: number, tolerance = 0.6) =>+ Math.abs(actual - expected) <= tolerance;++ check(storybookSha === checkoutSha, 'storybook build mismatch');+ check(pageErrors.length === 0, `page errors: ${pageErrors.join(' | ')}`);+ check(!observed.storybookError, 'storybook error display');+ check(observed.theme === item.theme, `theme ${observed.theme}`);+ check(observed.mode === item.mode, `mode ${observed.mode}`);+ check(+ observed.viewport.width === item.viewport.width &&+ observed.viewport.height === item.viewport.height,+ 'viewport mismatch',+ );+ check(observed.dpr === 2, `dpr ${observed.dpr}`);+ check(observed.reducedMotion, 'reduced motion not applied');+ check(observed.fonts === 'loaded', `fonts ${observed.fonts}`);+ check(geometryStable, 'geometry changed between samples');+ check(+ observed.layouts.length === LAYOUTS[item.story],+ `${observed.layouts.length} layouts, expected ${LAYOUTS[item.story]}`,+ );+ if (item.viewport !== NARROW) {+ check(+ observed.documentOverflow <= 0,+ `document scrolls sideways by ${observed.documentOverflow}px`,+ );+ }++ observed.layouts.forEach((layout, index) => {+ const where = `layout ${index}`;+ // Layout adds no role or name.+ check(+ layout.role == null &&+ layout.ariaLabel == null &&+ layout.ariaLabelledby == null,+ `${where} role ${layout.role} label ${layout.ariaLabel} labelledby ${layout.ariaLabelledby}`,+ );+ // One `layout` target that reflects height; Layout paints nothing.+ check(+ JSON.stringify(layout.targets) === '["astryx-layout"]',+ `${where} targets ${layout.targets.join(' ')}`,+ );+ check(+ layout.height === 'fill' || layout.height === 'auto',+ `${where} data-height ${layout.height}`,+ );+ check(+ layout.background === 'rgba(0, 0, 0, 0)',+ `${where} paints background ${layout.background}`,+ );+ check(+ layout.direction === item.direction,+ `${where} direction ${layout.direction}`,+ );+ // The root escapes the published container padding on all four+ // edges, and the inner stack publishes zero.+ for (const [edge, value] of Object.entries(layout.parentPublished)) {+ const margin =+ layout.margins[edge as keyof typeof layout.margins] ?? NaN;+ check(+ near(margin, -value),+ `${where} margin ${edge} ${margin}, expected ${-value}`,+ );+ }+ check(+ layout.innerPublished != null &&+ Object.values(layout.innerPublished).every(value => value === 0),+ `${where} inner stack publishes ${JSON.stringify(layout.innerPublished)}`,+ );+ // Header, then the middle row, then footer, in DOM and on screen;+ // the start panel sits at the inline start of the content.+ const rank = {header: 0, panel: 1, content: 1, footer: 2} as const;+ const kinds = layout.regions.map(region => region.kind);+ const ranks = kinds.map(kind => (kind == null ? -1 : rank[kind]));+ check(+ ranks.every((value, at) => at === 0 || value >= ranks[at - 1]),+ `${where} region order ${kinds.join(',')}`,+ );+ const contentAt = kinds.indexOf('content');+ const header = layout.regions.find(region => region.kind === 'header');+ const footer = layout.regions.find(region => region.kind === 'footer');+ layout.regions.forEach((region, at) => {+ const label = `${where} ${region.kind} ${at}`;+ check(+ region.box.left >= layout.box.left - 0.5 &&+ region.box.right <= layout.box.right + 0.5,+ `${label} ${JSON.stringify(region.box)} leaves layout ${JSON.stringify(layout.box)}`,+ );+ if (region.kind === 'panel' || region.kind === 'content') {+ if (header != null) {+ check(+ region.box.top >= header.box.bottom - 0.5,+ `${label} starts above the header`,+ );+ }+ if (footer != null) {+ check(+ region.box.bottom <= footer.box.top + 0.5,+ `${label} ends below the footer`,+ );+ }+ }+ if (region.kind === 'panel' && contentAt >= 0) {+ const content = layout.regions[contentAt].box;+ const isStart = at < contentAt;+ const towardStart =+ item.direction === 'rtl'+ ? region.box.left >= content.right - 0.5+ : region.box.right <= content.left + 0.5;+ const towardEnd =+ item.direction === 'rtl'+ ? region.box.right <= content.left + 0.5+ : region.box.left >= content.right - 0.5;+ check(+ isStart ? towardStart : towardEnd,+ `${label} is not at the inline ${isStart ? 'start' : 'end'} of the content`,+ );+ }+ });+ });++ // A slot left `false` by `isOpen && <Region />` is+ // absent. The closed column matches the column that omits the slots,+ // and a closed end panel gives the no-panel content-width composition.+ if (item.story === 'closed-regions') {+ const {omitted, closed, contentWidth} = observed.closed;+ check(+ omitted?.found === true &&+ closed?.found === true &&+ contentWidth?.found === true,+ 'closed-regions fixtures missing',+ );+ if (omitted?.found && closed?.found) {+ check(+ JSON.stringify(closed.regionKinds) === '["content"]',+ `closed layout renders ${closed.regionKinds.join(',')}`,+ );+ for (const [side, value] of Object.entries(omitted.contentPadding)) {+ const actual =+ closed.contentPadding[side as keyof typeof closed.contentPadding];+ check(+ near(actual, value),+ `closed content padding ${side} ${actual}, expected ${value} as when the slots are omitted`,+ );+ }+ for (const [side, value] of Object.entries(omitted.contentOffset)) {+ const actual =+ closed.contentOffset[side as keyof typeof closed.contentOffset];+ check(+ near(actual, value),+ `closed content offset ${side} ${actual}, expected ${value} as when the slots are omitted`,+ );+ }+ }+ if (contentWidth?.found) {+ check(+ JSON.stringify(contentWidth.regionKinds) === '["header","content"]',+ `content-width layout renders ${contentWidth.regionKinds.join(',')}`,+ );+ check(+ near(contentWidth.contentBox.left, contentWidth.rootBox.left) &&+ near(contentWidth.contentBox.right, contentWidth.rootBox.right),+ `content ${JSON.stringify(contentWidth.contentBox)} does not span the layout ${JSON.stringify(contentWidth.rootBox)}`,+ );+ }+ }++ const png = await page.screenshot({animations: 'disabled', fullPage: true});+ check(png.length > 1000, 'screenshot is empty');+ const image = `${item.key}.png`;+ const receipt = {+ schemaVersion: 1,+ expected: {+ build: checkoutSha,+ storyId: `core-layout--${item.story}`,+ mode: item.mode,+ theme: item.theme,+ direction: item.direction,+ viewport: item.viewport,+ layouts: LAYOUTS[item.story],+ anatomy:+ 'each Layout root carries only the astryx-layout target, reflects data-height fill or auto, paints no background, and has no role, aria-label, or aria-labelledby',+ padding:+ 'each root margin is the negative of the container padding published to it on all four edges; the inner stack publishes zero on all four edges',+ order:+ 'regions run header, middle row, footer in DOM and on screen; panels and content sit below the header and above the footer; a panel before the content sits at its inline start and one after it at its inline end; every region stays inside its layout horizontally',+ closedRegions:+ item.story === 'closed-regions'+ ? 'the closed layout renders only content, with the same padding and the same offsets inside its card as the layout that omits the slots; with contentWidth and a closed end panel, the content spans the whole layout'+ : 'not applicable',+ overflow:+ item.viewport === NARROW+ ? 'not asserted at the document: the story frames are wider than 320px; regions stay inside their layouts'+ : 'no sideways document scroll',+ },+ observed: {+ build: storybookSha,+ ...observed,+ geometryStable,+ pageErrors,+ },+ image: {+ file: image,+ sha256: createHash('sha256').update(png).digest('hex'),+ width: png.readUInt32BE(16),+ height: png.readUInt32BE(20),+ },+ failures,+ passed: failures.length === 0,+ };+ fs.writeFileSync(path.join(OUTPUT, image), png);+ fs.writeFileSync(+ path.join(OUTPUT, `${item.key}.sensors.json`),+ `${JSON.stringify(receipt, null, 2)}\n`,+ );+ await context.close();+ expect(failures).toEqual([]);+ });+}++test('manifest is complete', async () => {+ // Read only this run's frames, so files left by another run do not count.+ const receipts = cases.map(item => {+ const file = path.join(OUTPUT, `${item.key}.sensors.json`);+ return {+ key: item.key,+ receipt: fs.existsSync(file)+ ? (JSON.parse(fs.readFileSync(file, 'utf8')) as AuditReceipt)+ : null,+ };+ });+ fs.writeFileSync(+ path.join(OUTPUT, 'manifest.json'),+ `${JSON.stringify(+ {+ schemaVersion: 1,+ component: 'core/Layout',+ build: checkoutSha,+ frames: cases.map(item => ({+ key: item.key,+ image: `${item.key}.png`,+ receipt: `${item.key}.sensors.json`,+ })),+ },+ null,+ 2,+ )}\n`,+ );+ expect(+ receipts.filter(({receipt}) => receipt == null).map(({key}) => key),+ ).toEqual([]);+ // A receipt left by an earlier build does not count.+ expect(+ receipts+ .filter(({receipt}) => receipt?.expected.build !== checkoutSha)+ .map(({key}) => key),+ ).toEqual([]);+ expect(+ receipts+ .filter(({receipt}) => receipt?.passed !== true)+ .map(({key, receipt}) => ({frame: key, failures: receipt?.failures})),+ ).toEqual([]);+});