An open source design system that's fully customizable and agent ready
TypeScript
feat(tablist): add isFullBleed to bleed a tab bar to container edges (#3938)
Jiun Shin53112ff975f5
diff --git a/.changeset/tablist-add-isfullbleed-to-bleed-a-tab-bar-to-it-mlxn.md b/.changeset/tablist-add-isfullbleed-to-bleed-a-tab-bar-to-it-mlxn.mdnew file mode 100644index 0000000000..66fcfd7615--- /dev/null+++ b/.changeset/tablist-add-isfullbleed-to-bleed-a-tab-bar-to-it-mlxn.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+'@astryxdesign/cli': patch+---++[feat] TabList: add an `isFullBleed` prop so a tab bar can bleed out to its container's inline content edges instead of requiring hand-written negative-margin CSS (#2622). Like Divider's `isFullBleed`, it cancels the nearest padded Layout container's `--container-padding-inline-*` custom properties with negative margins; the inner strip pads back by the amount the bleed exceeds a tab stop's own padding so edge labels remain aligned to the content inset. It is inline-only: TabList owns the inline full bleed, and the container owns the block-end dock. For that, LayoutHeader gains a `paddingBlockEnd` per-edge override in Section's existing spelling — `paddingBlockEnd={0}` docks the header's last child on its bottom edge so a tab strip's underline meets `hasDivider` at any header padding. The `detail-page` template now uses both props, aligns its ghost panel toggle with the container inset, and no longer carries any hand-written tab-row CSS.+@jiunshinndiff --git a/.github/scripts/story-play-guard.js b/.github/scripts/story-play-guard.jsnew file mode 100644index 0000000000..bf9df22e67--- /dev/null+++ b/.github/scripts/story-play-guard.js@@ -0,0 +1,204 @@+#!/usr/bin/env node+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @description Runs listed stories' play functions in real Chromium and fails when one throws+ * @input --storybook-dir <path> [--port <n>]+ * @output One line per story; exit 1 if a play function threw, the story errored, or it never finished+ *+ * A story's play function is the only place a geometry assertion can live —+ * getBoundingClientRect needs a real layout engine — but on its own it is+ * observed by nothing that can fail: Vitest collects only `*.test.*` files,+ * and the visual gate loads each story waiting for rendered DOM without+ * awaiting or inspecting the play result. A broken play assertion therefore+ * leaves every required check green (PR #3938 round 3).+ *+ * This guard closes that gap. It serves the built Storybook, loads each+ * listed story's iframe in Chromium, and listens on the preview channel for+ * the play outcome: `storyRendered` only fires after `play` resolves, and+ * any thrown assertion surfaces as `playFunctionThrewException` (or one of+ * its sibling error events). No outcome within the timeout also fails —+ * a story that cannot boot must not pass by silence.+ */++const { chromium } = require('playwright');+const fs = require('node:fs');+const path = require('node:path');+const http = require('node:http');++const args = process.argv.slice(2);+const getArg = (name) => {+ const idx = args.indexOf(`--${name}`);+ return idx !== -1 ? args[idx + 1] : null;+};++const storybookDir = getArg('storybook-dir') || 'apps/storybook/dist';+const port = Number(getArg('port') || 6010);++// Stories whose play assertions are load-bearing. Adding a story here is the+// whole cost of promoting its play function into required CI.+const TARGETS = [+ {+ component: 'TabList',+ story: 'core-tablist--full-bleed-geometry',+ guards:+ 'isFullBleed strip/label geometry incl. clamp far side, and the real ' ++ 'LayoutHeader paddingBlockEnd -> TabList isFullBleed dock (#2622)',+ },+];++const CONTENT_TYPES = {+ '.html': 'text/html',+ '.js': 'application/javascript',+ '.css': 'text/css',+ '.json': 'application/json',+ '.png': 'image/png',+ '.svg': 'image/svg+xml',+};++function createServer(dir, listenPort) {+ return new Promise((resolve) => {+ const server = http.createServer((req, res) => {+ const filePath = path+ .join(dir, req.url === '/' ? 'index.html' : req.url)+ .split('?')[0];++ const resolved = path.resolve(filePath);+ if (!resolved.startsWith(path.resolve(dir))) {+ res.writeHead(403);+ res.end('Forbidden');+ return;+ }++ fs.readFile(resolved, (err, data) => {+ if (err) {+ res.writeHead(404);+ res.end('Not found');+ return;+ }+ res.writeHead(200, {+ 'Content-Type':+ CONTENT_TYPES[path.extname(resolved)] || 'text/plain',+ });+ res.end(data);+ });+ });++ server.listen(listenPort, () => resolve(server));+ });+}++// Records the story's play outcome from the preview channel. `storyRendered`+// is emitted only after the play function resolves; every failure mode has+// its own event. Attached before any preview code runs so no event is missed.+function recordStoryOutcome() {+ window.__storyOutcome = { done: false, errors: [] };+ const ERROR_EVENTS = [+ 'playFunctionThrewException',+ 'unhandledErrorsWhilePlaying',+ 'storyThrewException',+ 'storyErrored',+ 'storyMissing',+ ];+ const describe = (payload) => {+ if (payload == null) return '';+ if (typeof payload === 'string') return payload;+ return [payload.name, payload.title, payload.message, payload.description]+ .filter(Boolean)+ .join(': ');+ };+ const attach = () => {+ const channel = window.__STORYBOOK_ADDONS_CHANNEL__;+ if (!channel) {+ setTimeout(attach, 50);+ return;+ }+ channel.on('storyRendered', () => {+ window.__storyOutcome.done = true;+ });+ for (const event of ERROR_EVENTS) {+ channel.on(event, (payload) => {+ window.__storyOutcome.errors.push(+ `${event}${describe(payload) ? ` — ${describe(payload)}` : ''}`+ );+ window.__storyOutcome.done = true;+ });+ }+ };+ attach();+}++async function probe(page, target) {+ await page.addInitScript(recordStoryOutcome);+ await page.goto(+ `http://localhost:${port}/iframe.html?id=${target.story}&viewMode=story`,+ { waitUntil: 'domcontentloaded', timeout: 30000 }+ );+ await page.waitForFunction(+ () => window.__storyOutcome && window.__storyOutcome.done === true,+ null,+ { timeout: 30000 }+ );+ return page.evaluate(() => window.__storyOutcome);+}++async function run() {+ const dir = path.resolve(process.cwd(), storybookDir);+ if (!fs.existsSync(dir)) {+ console.error(`Storybook build not found at ${dir}`);+ return 1;+ }++ const server = await createServer(dir, port);+ const browser = await chromium.launch();+ let failures = 0;++ try {+ const context = await browser.newContext({+ viewport: { width: 1280, height: 900 },+ });++ for (const target of TARGETS) {+ const page = await context.newPage();+ try {+ const outcome = await probe(page, target);+ if (outcome.errors.length > 0) {+ failures++;+ console.error(+ `✗ ${target.component} (${target.story}):\n ${outcome.errors.join('\n ')}`+ );+ } else {+ console.log(+ `✓ ${target.component} (${target.story}): play passed — ${target.guards}`+ );+ }+ } catch (e) {+ failures++;+ console.error(+ `✗ ${target.component} (${target.story}): no play outcome — ${e.message}`+ );+ } finally {+ await page.close();+ }+ }+ } finally {+ await browser.close();+ server.close();+ }++ if (failures > 0) {+ console.error(`\nFailing: ${failures} story play function(s) did not pass.`);+ return 1;+ }+ console.log('\nAll story play guards passed.');+ return 0;+}++run()+ .then((code) => {+ process.exitCode = code;+ })+ .catch((e) => {+ console.error('Story play guard failed:', e);+ process.exit(1);+ });diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 752c98e4e7..96f9d157bd 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -569,6 +569,16 @@ jobs:- name: Run theme var reachability guardrun: node .github/scripts/theme-var-reachability.js --storybook-dir apps/storybook/dist+ # A story play function is where geometry assertions live (they need+ # getBoundingClientRect, so jsdom is out), but nothing else observes the+ # result: Vitest never collects stories, and pr-visual loads stories+ # without awaiting `play` — and is soft while it earns trust. This guard+ # loads each listed story in Chromium and fails when its play assertions+ # throw. Hosted here with the sibling Chromium guards because pr-a11y is+ # the blocking job that runs whenever components change.+ - name: Run story play guard+ run: node .github/scripts/story-play-guard.js --storybook-dir apps/storybook/dist+# The layer order Astryx promises is Astryx < theme < product, and which# declaration paints is a cascade fact no jsdom test can settle: the build has# been wrong in both directions inside one week — unsplit, so StyleX outrankeddiff --git a/apps/storybook/stories/TabList.stories.tsx b/apps/storybook/stories/TabList.stories.tsxindex 306f2a7792..f88ab8d6d8 100644--- a/apps/storybook/stories/TabList.stories.tsx+++ b/apps/storybook/stories/TabList.stories.tsx@@ -1,10 +1,21 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {useState} from 'react';+import {useState, type CSSProperties} from 'react';import type {Meta, StoryObj} from '@storybook/react';import {TabList, Tab, TabMenu} from '@astryxdesign/core/TabList';import {Button} from '@astryxdesign/core/Button';-import {PlusIcon, FunnelIcon} from '@heroicons/react/24/outline';+import {+ LayoutHeader,+ VStack,+ HStack,+ StackItem,+} from '@astryxdesign/core/Layout';+import {Heading} from '@astryxdesign/core/Text';+import {+ PlusIcon,+ FunnelIcon,+ ViewColumnsIcon,+} from '@heroicons/react/24/outline';const meta: Meta<typeof TabList> = {title: 'Core/TabList',@@ -38,6 +49,559 @@ export const Default: Story = {},};+const FULL_BLEED_FIXTURE_PADDING = 16;+// The clamp's far side: container padding below a stop's own 12px inline+// padding, where the strip's pad-back clamps to zero and the stop's own inset+// is preserved instead of shrunk.+const CLAMP_FIXTURE_PADDING = 8;++function fullBleedFixtureStyle(padding: number): CSSProperties & {+ '--container-padding-inline-start': string;+ '--container-padding-inline-end': string;+} {+ return {+ boxSizing: 'border-box',+ width: 480,+ paddingInline: padding,+ '--container-padding-inline-start': `${padding}px`,+ '--container-padding-inline-end': `${padding}px`,+ };+}++/**+ * The header seam the `detail-page` template ships. `padding` publishes the+ * inline inset through the container-padding protocol and `paddingBlockEnd={0}`+ * docks the header's last child on its bottom edge, so these two fixtures+ * exercise the real `LayoutHeader` -> `TabList isFullBleed` wiring rather than+ * hand-written custom properties. Every expected number below is read back+ * from the rendered DOM, never restated here.+ */+const HEADER_DOCK_PADDING_STEP = 4;+/**+ * A step away from `HEADER_DOCK_PADDING_STEP` on purpose. LayoutHeader's inner+ * wrapper falls back to `--spacing-4` when no padding is published, so a+ * fixture at step 4 alone could pass on a stale fallback. At step 6 the+ * published inset and that fallback disagree, and every number below is only+ * reachable through the variables `padding` actually publishes.+ */+const HEADER_FILL_PADDING_STEP = 6;+const HEADER_FIXTURE_WIDTH = 640;++function assertGeometry(label: string, actual: number, expected: number) {+ if (Math.abs(actual - expected) > 0.5) {+ throw new Error(+ `${label}: expected ${expected.toFixed(2)}px, received ${actual.toFixed(2)}px`,+ );+ }+}++const px = (value: string) => Number.parseFloat(value);++/**+ * Browser geometry guard for `isFullBleed`. The strip must escape the+ * wrapper's padding while the first label returns to the content inset. The+ * strip-pad assertion also pins TabList's restated stop-padding token to the+ * padding the real Tab paints; changing either side breaks this story. The+ * clamp and no-op fixtures cover the accepted far side: container padding+ * below a stop's own inset preserves that inset, and outside a padded+ * container the prop changes nothing.+ *+ * The first four fixtures hand-write the `--container-padding-inline-*`+ * values on a plain wrapper, which pins TabList's half of the contract but+ * proves nothing about who publishes those values. The two `header-*`+ * fixtures close that: they compose a real+ * `LayoutHeader hasDivider padding paddingBlockEnd={0}` around a real+ * `TabList isFullBleed` — the shape the `detail-page` template ships — so the+ * whole seam is measured, publisher included.+ *+ * Enforced by `.github/scripts/story-play-guard.js` in the `pr-a11y` job —+ * the play assertions below fail required CI, not just a local canvas.+ */+export const FullBleedGeometry: Story = {+ render: () => {+ const [value, setValue] = useState('home');+ return (+ <div style={{display: 'flex', flexDirection: 'column', gap: 24}}>+ <div+ data-full-bleed-fixture="hug"+ style={fullBleedFixtureStyle(FULL_BLEED_FIXTURE_PADDING)}>+ <TabList+ value={value}+ onChange={setValue}+ aria-label="Hug full-bleed geometry"+ isFullBleed>+ <Tab value="home" label="Home" />+ <Tab value="projects" label="Projects" />+ </TabList>+ </div>+ <div+ data-full-bleed-fixture="fill"+ style={fullBleedFixtureStyle(FULL_BLEED_FIXTURE_PADDING)}>+ <TabList+ value={value}+ onChange={setValue}+ aria-label="Fill full-bleed geometry"+ layout="fill"+ isFullBleed>+ <Tab value="home" label="Home" />+ <Tab value="projects" label="Projects" />+ <TabMenu+ label="More"+ options={[+ {value: 'settings', label: 'Settings'},+ {value: 'billing', label: 'Billing'},+ ]}+ />+ </TabList>+ </div>+ <div+ data-full-bleed-fixture="clamp"+ style={fullBleedFixtureStyle(CLAMP_FIXTURE_PADDING)}>+ <TabList+ value={value}+ onChange={setValue}+ aria-label="Clamp full-bleed geometry"+ isFullBleed>+ <Tab value="home" label="Home" />+ <Tab value="projects" label="Projects" />+ </TabList>+ </div>+ <div+ data-full-bleed-fixture="noop"+ style={{boxSizing: 'border-box', width: 480}}>+ <TabList+ value={value}+ onChange={setValue}+ aria-label="No-op full-bleed geometry"+ isFullBleed>+ <Tab value="home" label="Home" />+ <Tab value="projects" label="Projects" />+ </TabList>+ </div>+ <div+ data-full-bleed-fixture="noop-control"+ style={{boxSizing: 'border-box', width: 480}}>+ <TabList+ value={value}+ onChange={setValue}+ aria-label="No-op control geometry">+ <Tab value="home" label="Home" />+ <Tab value="projects" label="Projects" />+ </TabList>+ </div>+ {/* The shipped seam, composed exactly as `detail-page` composes it:+ a padded LayoutHeader with its divider, its block-end padding+ docked to 0, and the tab row as the last thing in the header. */}+ <div+ data-full-bleed-fixture="header-dock"+ style={{boxSizing: 'border-box', width: HEADER_FIXTURE_WIDTH}}>+ <LayoutHeader+ hasDivider+ padding={HEADER_DOCK_PADDING_STEP}+ paddingBlockEnd={0}>+ <VStack gap={3}>+ <Heading level={2} maxLines={1}>+ Order #1001+ </Heading>+ <HStack vAlign="center">+ <StackItem size="fill">+ <TabList+ value={value}+ onChange={setValue}+ size="lg"+ aria-label="Header dock full-bleed geometry"+ isFullBleed>+ <Tab value="home" label="Details" />+ <Tab value="projects" label="Invoices" />+ <Tab value="timeline" label="Timeline" />+ <TabMenu+ label="More"+ options={[+ {value: 'customer', label: 'Customer'},+ {value: 'analysis', label: 'Analysis'},+ ]}+ />+ </TabList>+ </StackItem>+ <Button+ label="Show panel"+ variant="ghost"+ size="md"+ icon={<ViewColumnsIcon />}+ isIconOnly+ />+ </HStack>+ </VStack>+ </LayoutHeader>+ </div>+ {/* Same header wiring with the strip as the header's only child, so+ both inline edges are free to reach the header's box and the last+ stop's far label can be measured against the end inset. */}+ <div+ data-full-bleed-fixture="header-fill"+ style={{boxSizing: 'border-box', width: HEADER_FIXTURE_WIDTH}}>+ <LayoutHeader+ hasDivider+ padding={HEADER_FILL_PADDING_STEP}+ paddingBlockEnd={0}>+ <TabList+ value={value}+ onChange={setValue}+ size="lg"+ layout="fill"+ aria-label="Header fill full-bleed geometry"+ isFullBleed>+ <Tab value="home" label="Details" />+ <Tab value="projects" label="Invoices" />+ <TabMenu+ label="More"+ options={[+ {value: 'customer', label: 'Customer'},+ {value: 'analysis', label: 'Analysis'},+ ]}+ />+ </TabList>+ </LayoutHeader>+ </div>+ </div>+ );+ },+ play: async ({canvasElement}) => {+ await document.fonts.ready;+ await new Promise<void>(resolve =>+ requestAnimationFrame(() => requestAnimationFrame(() => resolve())),+ );++ const wrapper = canvasElement.querySelector<HTMLElement>(+ '[data-full-bleed-fixture="hug"]',+ );+ const strip = wrapper?.querySelector<HTMLElement>('.astryx-tab-strip');+ const firstStop = strip?.querySelector<HTMLElement>(+ '[data-tab-value="home"]',+ );+ const firstLabel = firstStop?.querySelector<HTMLElement>('span span');+ const fillWrapper = canvasElement.querySelector<HTMLElement>(+ '[data-full-bleed-fixture="fill"]',+ );+ const fillStrip =+ fillWrapper?.querySelector<HTMLElement>('.astryx-tab-strip');+ const lastStop = fillStrip?.querySelector<HTMLElement>('[data-tab-menu]');+ const clampWrapper = canvasElement.querySelector<HTMLElement>(+ '[data-full-bleed-fixture="clamp"]',+ );+ const clampStrip =+ clampWrapper?.querySelector<HTMLElement>('.astryx-tab-strip');+ const clampFirstStop = clampStrip?.querySelector<HTMLElement>(+ '[data-tab-value="home"]',+ );+ const clampFirstLabel =+ clampFirstStop?.querySelector<HTMLElement>('span span');+ const noopStrip = canvasElement.querySelector<HTMLElement>(+ '[data-full-bleed-fixture="noop"] .astryx-tab-strip',+ );+ const noopControlStrip = canvasElement.querySelector<HTMLElement>(+ '[data-full-bleed-fixture="noop-control"] .astryx-tab-strip',+ );++ if (+ !wrapper ||+ !strip ||+ !firstStop ||+ !firstLabel ||+ !fillWrapper ||+ !fillStrip ||+ !lastStop ||+ !clampWrapper ||+ !clampStrip ||+ !clampFirstStop ||+ !clampFirstLabel ||+ !noopStrip ||+ !noopControlStrip+ ) {+ throw new Error('Full-bleed geometry fixture did not render as expected');+ }++ const wrapperRect = wrapper.getBoundingClientRect();+ const stripRect = strip.getBoundingClientRect();+ const firstStopRect = firstStop.getBoundingClientRect();+ const lastStopRect = lastStop.getBoundingClientRect();+ const fillWrapperRect = fillWrapper.getBoundingClientRect();+ const firstLabelRect = firstLabel.getBoundingClientRect();+ const stopPadding = Number.parseFloat(+ getComputedStyle(firstStop).paddingInlineStart,+ );+ const lastStopPadding = Number.parseFloat(+ getComputedStyle(lastStop).paddingInlineEnd,+ );+ const stripPadding = Number.parseFloat(+ getComputedStyle(strip).paddingInlineStart,+ );+ const stripPaddingEnd = Number.parseFloat(+ getComputedStyle(fillStrip).paddingInlineEnd,+ );+ const contentInset = wrapperRect.left + FULL_BLEED_FIXTURE_PADDING;+ const contentEnd = fillWrapperRect.right - FULL_BLEED_FIXTURE_PADDING;++ assertGeometry('strip box start', stripRect.left, wrapperRect.left);+ assertGeometry('first label start', firstLabelRect.left, contentInset);+ assertGeometry(+ 'stop padding coupling',+ stripPadding,+ FULL_BLEED_FIXTURE_PADDING - stopPadding,+ );+ assertGeometry(+ 'first stop content start',+ firstStopRect.left + stopPadding,+ contentInset,+ );+ assertGeometry(+ 'TabMenu padding coupling',+ stripPaddingEnd,+ FULL_BLEED_FIXTURE_PADDING - lastStopPadding,+ );+ assertGeometry(+ 'last stop content end',+ lastStopRect.right - lastStopPadding,+ contentEnd,+ );++ // Far side of the clamp: at 8px container padding the strip still bleeds+ // to the wrapper edge, but the pad-back clamps to zero — the stop's own+ // 12px inset is preserved, never shrunk, so the label sits 4px inside the+ // content inset (matching main's behaviour with hand-written margins).+ const clampWrapperRect = clampWrapper.getBoundingClientRect();+ const clampStripRect = clampStrip.getBoundingClientRect();+ const clampLabelRect = clampFirstLabel.getBoundingClientRect();+ const clampStopPadding = Number.parseFloat(+ getComputedStyle(clampFirstStop).paddingInlineStart,+ );+ const clampStripPadding = Number.parseFloat(+ getComputedStyle(clampStrip).paddingInlineStart,+ );++ assertGeometry(+ 'clamp strip box start',+ clampStripRect.left,+ clampWrapperRect.left,+ );+ assertGeometry('clamp strip pad-back', clampStripPadding, 0);+ assertGeometry(+ 'clamp preserves stop inset',+ clampLabelRect.left,+ clampWrapperRect.left + clampStopPadding,+ );+ if (clampStopPadding <= CLAMP_FIXTURE_PADDING) {+ throw new Error(+ `clamp fixture is not on the far side: stop padding ${clampStopPadding}px must exceed the ${CLAMP_FIXTURE_PADDING}px container padding`,+ );+ }++ // Outside a padded container the custom properties are unset and the prop+ // is a no-op: the strip's box and padding match a plain TabList exactly.+ const noopStripRect = noopStrip.getBoundingClientRect();+ const noopControlRect = noopControlStrip.getBoundingClientRect();+ assertGeometry(+ 'no-op strip start',+ noopStripRect.left,+ noopControlRect.left,+ );+ assertGeometry(+ 'no-op strip end',+ noopStripRect.right,+ noopControlRect.right,+ );+ assertGeometry(+ 'no-op strip padding',+ Number.parseFloat(getComputedStyle(noopStrip).paddingInlineStart),+ Number.parseFloat(getComputedStyle(noopControlStrip).paddingInlineStart),+ );++ // ── The real seam ──────────────────────────────────────────────────────+ // Everything above runs against hand-written custom properties. What+ // ships is a LayoutHeader publishing them, so measure that instead.++ /** Resolves one `header-*` fixture's parts, or throws naming the gap. */+ const headerParts = (name: string) => {+ const fixture = canvasElement.querySelector<HTMLElement>(+ `[data-full-bleed-fixture="${name}"]`,+ );+ const header = fixture?.querySelector<HTMLElement>(+ '.astryx-layout-header',+ );+ // LayoutHeader's padded inner wrapper: the element that both applies the+ // padding and publishes the container-padding variables.+ const inner = header?.firstElementChild as HTMLElement | null;+ const nav = fixture?.querySelector<HTMLElement>('.astryx-tab-list');+ const strip = fixture?.querySelector<HTMLElement>('.astryx-tab-strip');+ const firstStop = fixture?.querySelector<HTMLElement>(+ '[data-tab-value="home"]',+ );+ const indicator = firstStop?.querySelector<HTMLElement>(+ '.astryx-tab-indicator',+ );+ if (!fixture || !header || !inner || !nav || !strip || !firstStop) {+ throw new Error(`${name} header fixture did not render as expected`);+ }+ if (!indicator) {+ throw new Error(`${name}: selected tab has no indicator to dock`);+ }+ const headerStyle = getComputedStyle(header);+ const innerStyle = getComputedStyle(inner);+ return {+ header,+ headerRect: header.getBoundingClientRect(),+ dividerWidth: px(headerStyle.borderBlockEndWidth),+ inner,+ innerRect: inner.getBoundingClientRect(),+ padStart: px(innerStyle.paddingInlineStart),+ padEnd: px(innerStyle.paddingInlineEnd),+ padBlockEnd: px(innerStyle.paddingBlockEnd),+ varStart: px(+ innerStyle.getPropertyValue('--container-padding-inline-start'),+ ),+ varEnd: px(+ innerStyle.getPropertyValue('--container-padding-inline-end'),+ ),+ varBlockEnd: px(+ innerStyle.getPropertyValue('--container-padding-block-end'),+ ),+ nav,+ navRect: nav.getBoundingClientRect(),+ strip,+ stripRect: strip.getBoundingClientRect(),+ stripPadStart: px(getComputedStyle(strip).paddingInlineStart),+ stripPadEnd: px(getComputedStyle(strip).paddingInlineEnd),+ firstStop,+ firstStopRect: firstStop.getBoundingClientRect(),+ firstStopPad: px(getComputedStyle(firstStop).paddingInlineStart),+ indicatorRect: indicator.getBoundingClientRect(),+ };+ };++ /**+ * What both header fixtures owe regardless of their contents: the header+ * publishes the padding it actually applies (the coupling the whole bleed+ * rests on), the tab row is docked on the header's content bottom edge,+ * and the selected underline lands on the divider rather than floating+ * above it. Round 3 measured that underline 7.00px above the divider with+ * the template's hand-written margins; docked it reads -1.00px — the 2px+ * indicator's top edge one pixel above the 1px divider's top edge, its+ * bottom flush with the divider's outer edge.+ */+ const assertHeaderSeam = (+ name: string,+ p: ReturnType<typeof headerParts>,+ ) => {+ assertGeometry(+ `${name}: published inline-start inset`,+ p.varStart,+ p.padStart,+ );+ assertGeometry(`${name}: published inline-end inset`, p.varEnd, p.padEnd);+ assertGeometry(`${name}: block-end padding docked`, p.padBlockEnd, 0);+ assertGeometry(+ `${name}: published block-end inset`,+ p.varBlockEnd,+ p.padBlockEnd,+ );++ // paddingBlockEnd={0} is the whole reason the tab row can reach the+ // rail: its bottom edge is the header's content bottom edge.+ assertGeometry(+ `${name}: tab row on the header content edge`,+ p.navRect.bottom,+ p.innerRect.bottom,+ );++ const dividerTop = p.headerRect.bottom - p.dividerWidth;+ const overhang = p.indicatorRect.height - p.dividerWidth;+ assertGeometry(+ `${name}: underline docks on the divider`,+ p.indicatorRect.bottom,+ p.headerRect.bottom,+ );+ assertGeometry(+ `${name}: underline top relative to the divider rail`,+ p.indicatorRect.top - dividerTop,+ -overhang,+ );++ // The inline bleed itself, through the published variables: the strip's+ // box clears the header's inline-start padding, and it pads back by the+ // part of that inset a stop's own padding does not already supply.+ assertGeometry(+ `${name}: strip box start on the header edge`,+ p.stripRect.left,+ p.headerRect.left,+ );+ assertGeometry(+ `${name}: strip pad-back start`,+ p.stripPadStart,+ Math.max(p.padStart - p.firstStopPad, 0),+ );+ assertGeometry(+ `${name}: first stop content on the start inset`,+ p.firstStopRect.left + p.firstStopPad,+ p.headerRect.left + p.padStart,+ );+ };++ // Template mirror: tabs share the row with a trailing ghost toggle, so the+ // strip's end edge stops at that toggle. Its bleed is still measurable —+ // the box hangs the published end inset past its own StackItem.+ const dock = headerParts('header-dock');+ assertHeaderSeam('header-dock', dock);++ const dockLabel = dock.firstStop.querySelector<HTMLElement>('span span');+ const dockSlot = dock.nav.parentElement;+ if (!dockLabel || !dockSlot) {+ throw new Error('header-dock: tab label or stack slot did not render');+ }+ assertGeometry(+ 'header-dock: first label on the start inset',+ dockLabel.getBoundingClientRect().left,+ dock.headerRect.left + dock.padStart,+ );+ assertGeometry(+ 'header-dock: strip end bleeds past its stack slot',+ dock.navRect.right,+ dockSlot.getBoundingClientRect().right + dock.padEnd,+ );++ // Strip alone in the header, and at a different padding step: both inline+ // edges are free to reach the header's box, and the last stop's content+ // returns to the end inset.+ const fill = headerParts('header-fill');+ assertHeaderSeam('header-fill', fill);++ const fillMenu = fill.strip.querySelector<HTMLElement>('[data-tab-menu]');+ if (!fillMenu) {+ throw new Error('header-fill: TabMenu did not render');+ }+ if (Math.abs(fill.padStart - dock.padStart) < 0.5) {+ throw new Error(+ `header-fill must use a different padding step than header-dock, so a stale fallback cannot satisfy both; both measured ${fill.padStart.toFixed(2)}px`,+ );+ }+ assertGeometry(+ 'header-fill: strip box end on the header edge',+ fill.stripRect.right,+ fill.headerRect.right,+ );+ const fillMenuPadEnd = px(getComputedStyle(fillMenu).paddingInlineEnd);+ assertGeometry(+ 'header-fill: strip pad-back end',+ fill.stripPadEnd,+ Math.max(fill.padEnd - fillMenuPadEnd, 0),+ );+ assertGeometry(+ 'header-fill: last stop content on the end inset',+ fillMenu.getBoundingClientRect().right - fillMenuPadEnd,+ fill.headerRect.right - fill.padEnd,+ );+ },+};+export const WithMenu: Story = {args: {size: 'md',diff --git a/packages/cli/assets/templates/pages/detail-page/page.tsx b/packages/cli/assets/templates/pages/detail-page/page.tsxindex 40314412d0..a206ff10ed 100644--- a/packages/cli/assets/templates/pages/detail-page/page.tsx+++ b/packages/cli/assets/templates/pages/detail-page/page.tsx@@ -43,18 +43,9 @@ import {// ─── Styles ─────────────────────────────────────────────────────────────────import type {CSSProperties} from 'react';-// The only custom CSS in this template is small optical-alignment negative-// margins: LayoutHeader/TabList have no edge-dock prop (#2622) and List-// has no "bleed to container edge" prop (#2626). Everything else uses props.-// Plain inline styles — no StyleX compiler required.--// Bleed the tab bar to the header's content edges so the active-tab underline-// meets the header divider. No edge-dock prop on TabList (#2622).-const tabsRow: CSSProperties = {- marginInline: -12,- marginBottom: -16,- marginTop: 12,-};+// The only custom CSS in this template is a small optical-alignment negative+// margin: List has no "bleed to container edge" prop (#2626). Everything else+// uses props. Plain inline styles — no StyleX compiler required.// Pull the list items' inner padding back so their content optically aligns// with the section heading above (ListItem insets content by ~8px). No// edge/inset prop on List (#2626).@@ -176,7 +167,7 @@ function PageHeader({isNarrow: boolean;}) {return (- <LayoutHeader hasDivider padding={4}>+ <LayoutHeader hasDivider padding={4} paddingBlockEnd={0}><VStack gap={3}><HStack gap={4} vAlign="start"><StackItem size="fill">@@ -258,9 +249,13 @@ function PageHeader({</HStack>)}- <HStack vAlign="center" style={tabsRow}>+ <HStack vAlign="center"><StackItem size="fill">- <TabList value={activeTab} onChange={onTabChange} size="lg">+ <TabList+ value={activeTab}+ onChange={onTabChange}+ size="lg"+ isFullBleed><Tab value="details" label="Details" /><Tab value="invoices" label="Invoices" /><Tab value="timeline" label="Timeline" />diff --git a/packages/core/src/Layout/Layout.test.tsx b/packages/core/src/Layout/Layout.test.tsxindex 32bd34b6f1..94401f4821 100644--- a/packages/core/src/Layout/Layout.test.tsx+++ b/packages/core/src/Layout/Layout.test.tsx@@ -259,6 +259,70 @@ describe('Layout', () => {});});+ describe('LayoutHeader paddingBlockEnd', () => {+ /** StyleX classes on the header's inner (padding-owning) element, minus+ * dev-only provenance classes (they contain "__"). */+ function innerClassSet(container: HTMLElement): Set<string> {+ const inner = container.firstElementChild!+ .firstElementChild as HTMLElement;+ return new Set(+ inner.className+ .split(' ')+ .filter(Boolean)+ .filter(c => !c.includes('__') && !c.includes('.')),+ );+ }++ it('applies a class when paddingBlockEnd is set on its own', () => {+ const {container, rerender} = render(<LayoutHeader>H</LayoutHeader>);+ const baseline = innerClassSet(container);+ rerender(<LayoutHeader paddingBlockEnd={0}>H</LayoutHeader>);+ expect(innerClassSet(container)).not.toEqual(baseline);+ });++ it('overrides only the block-end edge of padding', () => {+ // padding={4} sets all four edges; paddingBlockEnd={0} may only move the+ // bottom edge, so every other padding class must survive unchanged.+ const {container, rerender} = render(+ <LayoutHeader padding={4}>H</LayoutHeader>,+ );+ const uniform = innerClassSet(container);+ rerender(+ <LayoutHeader padding={4} paddingBlockEnd={0}>+ H+ </LayoutHeader>,+ );+ const overridden = innerClassSet(container);+ const removed = [...uniform].filter(c => !overridden.has(c));+ const added = [...overridden].filter(c => !uniform.has(c));+ // Something block-end related was dropped and replaced...+ expect(removed.length).toBeGreaterThan(0);+ expect(added.length).toBeGreaterThan(0);+ // ...while the inline and block-start classes are shared by both renders.+ expect(uniform.size - removed.length).toBeGreaterThan(0);+ });++ it('spells the override with the shared per-edge family', () => {+ // The classes the override adds are exactly the ones the standalone+ // per-edge prop produces, so LayoutHeader and Section stay one family.+ const {container, rerender} = render(+ <LayoutHeader padding={4}>H</LayoutHeader>,+ );+ const uniform = innerClassSet(container);+ rerender(+ <LayoutHeader padding={4} paddingBlockEnd={0}>+ H+ </LayoutHeader>,+ );+ const added = [...innerClassSet(container)].filter(c => !uniform.has(c));+ rerender(<LayoutHeader paddingBlockEnd={0}>H</LayoutHeader>);+ const standalone = innerClassSet(container);+ for (const cls of added) {+ expect(standalone.has(cls)).toBe(true);+ }+ });+ });+describe('styling & ref', () => {it('forwards ref to the root div', () => {const ref = createRef<HTMLDivElement>();diff --git a/packages/core/src/Layout/LayoutHeader.doc.mjs b/packages/core/src/Layout/LayoutHeader.doc.mjsindex 5752d3a065..b2cea18b03 100644--- a/packages/core/src/Layout/LayoutHeader.doc.mjs+++ b/packages/core/src/Layout/LayoutHeader.doc.mjs@@ -39,6 +39,12 @@ export const docs = {type: 'string',description: 'Accessible label for the landmark element.',},+ {+ name: 'paddingBlockEnd',+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',+ description:+ 'Block-end (bottom) padding, using the spacing scale. Overrides padding on that edge only; paddingBlockEnd={0} docks the last child on the header bottom edge.',+ },{name: 'role',type: 'AriaRole',@@ -74,6 +80,12 @@ export const docsZh = {type: 'string',description: '地标元素的无障碍标签。',},+ {+ name: 'paddingBlockEnd',+ type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',+ description:+ '块结束(底部)内边距,使用间距刻度。仅在该边上覆盖 padding;paddingBlockEnd={0} 将最后一个子元素停靠在页眉底边。',+ },{name: 'role',type: 'AriaRole',@@ -92,6 +104,8 @@ export const docsDense = {hasDivider: 'Border at bottom edge.',height: 'Header height.',label: 'Accessible label for landmark element.',+ paddingBlockEnd:+ 'Block-end (bottom) padding override; wins over padding on that edge. 0 docks the last child on the header bottom edge.',role: 'ARIA landmark role.',},};diff --git a/packages/core/src/Layout/LayoutHeader.tsx b/packages/core/src/Layout/LayoutHeader.tsxindex d5a3706b76..be090b6c69 100644--- a/packages/core/src/Layout/LayoutHeader.tsx+++ b/packages/core/src/Layout/LayoutHeader.tsx@@ -11,6 +11,7 @@** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/Layout/Layout.doc.mjs+ * - /packages/core/src/Layout/LayoutHeader.doc.mjs* - /apps/storybook/stories/Layout.stories.tsx* - /packages/cli/assets/templates/blocks/components/Layout/ (showcase blocks)*/@@ -26,6 +27,7 @@ import type {SizeValue, SpacingStep} from '../utils/types';import {themeProps} from '../utils/themeProps';import {paddingStyles,+ paddingBlockEndStyles,containerPaddingInlineVarStyles,containerPaddingBlockStartVarStyles,containerPaddingBlockEndVarStyles,@@ -104,6 +106,15 @@ export interface LayoutHeaderProps extends BaseProps<HTMLDivElement> {*/padding?: SpacingStep;+ /**+ * Block-end (bottom) padding override. Takes precedence over `padding` on+ * that edge only; the block-start edge and both inline edges are left alone.+ * `paddingBlockEnd={0}` docks the last child on the header's bottom edge, so+ * a tab strip's underline meets `hasDivider` with no hand-written margin.+ * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.+ */+ paddingBlockEnd?: SpacingStep;+/*** Accessible label for the landmark.* Required when role is set and multiple landmarks of the same type exist.@@ -140,6 +151,7 @@ export function LayoutHeader({height,label,padding,+ paddingBlockEnd,role,xstyle,className,@@ -179,6 +191,12 @@ export function LayoutHeader({padding != null && containerPaddingInlineVarStyles[padding],padding != null && containerPaddingBlockStartVarStyles[padding],padding != null && containerPaddingBlockEndVarStyles[padding],+ // Per-edge override last so it wins over `padding` on its own edge.+ // The container var moves with it so bleed children compensate+ // against the padding actually applied, not the one asked for.+ paddingBlockEnd != null && paddingBlockEndStyles[paddingBlockEnd],+ paddingBlockEnd != null &&+ containerPaddingBlockEndVarStyles[paddingBlockEnd],)}>{children}</div>diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjsindex cf7c8b9893..81daa36102 100644--- a/packages/core/src/TabList/TabList.doc.mjs+++ b/packages/core/src/TabList/TabList.doc.mjs@@ -60,6 +60,12 @@ export const docs = {description: 'Whether to show a bottom border divider under the tab list.',default: 'false',},+ {+ name: 'isFullBleed',+ type: 'boolean',+ description: "Makes the tab strip escape its parent's container padding, extending to the container's content edges (cancels the nearest padded Layout container's --container-padding-* custom properties with negative margins). The inner strip pads back by the portion of the container inset that is not already supplied by the first or last tab stop, keeping edge labels aligned while a hasDivider underline spans the full content width. Matches Divider's isFullBleed: inline (start/end) edges only; block-edge docking stays with the surrounding layout.",+ default: 'false',+ },{name: 'role',type: 'AriaRole',@@ -104,6 +110,7 @@ export const docs = {{ guidance: true, description: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },{ guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm); the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },{ guidance: true, description: 'Reach for role="tablist" when the strip switches panels in place, and give each tab a panelId pointing at the panel it opens: that link is how a screen reader gets from a tab to its content. Leave it off for navigation between views.' },+ { guidance: true, description: 'Set isFullBleed to stretch a tab bar inside a padded LayoutHeader, Card, or Section to the container\'s inline content edges, instead of reaching for negative-margin CSS.' },{ guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },{ guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },{ guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },@@ -126,6 +133,7 @@ export const docsZh = {{ guidance: true, description: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },{ guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm); the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },{ guidance: true, description: 'Reach for role="tablist" when the strip switches panels in place, and give each tab a panelId pointing at the panel it opens: that link is how a screen reader gets from a tab to its content. Leave it off for navigation between views.' },+ { guidance: true, description: 'Set isFullBleed to stretch a tab bar inside a padded LayoutHeader, Card, or Section to the container\'s inline content edges, instead of reaching for negative-margin CSS.' },{ guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },{ guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },{ guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },@@ -149,6 +157,7 @@ export const docsDense = {{ guidance: true, description: 'Leave overflow handling on: a strip narrower than its tabs scrolls, and the selected tab is kept in view. Use TabMenu when you want a curated group of extra options rather than a scrolling strip.' },{ guidance: true, description: 'When using hasDivider with action buttons alongside tabs, match the Button size to the TabList size (both md, both sm); the divided tab strip reserves space so tabs and same-size buttons align to a shared baseline above the rail.' },{ guidance: true, description: 'Reach for role="tablist" when the strip switches panels in place, and give each tab a panelId pointing at the panel it opens: that link is how a screen reader gets from a tab to its content. Leave it off for navigation between views.' },+ { guidance: true, description: 'Set isFullBleed to stretch a tab bar inside a padded LayoutHeader, Card, or Section to the container\'s inline content edges, instead of reaching for negative-margin CSS.' },{ guidance: false, description: 'Use tabs for sequential steps or workflows; use a stepper or wizard pattern instead.' },{ guidance: false, description: 'Place more than 6–8 visible tabs before the overflow menu; prioritize the most important categories.' },{ guidance: false, description: 'Confuse TabList with SegmentedControl or ToggleButton. TabList is for navigation between views. SegmentedControl and ToggleButton are input controls: SegmentedControl always has exactly one selected option, while ToggleButton can be toggled on or off.' },@@ -159,4 +168,4 @@ export const docsDense = {{name: 'Right Content', required: false, description: 'Hugs content width.'},],},-};\ No newline at end of file+};diff --git a/packages/core/src/TabList/TabList.tsx b/packages/core/src/TabList/TabList.tsxindex fd176b98b4..65b8c12086 100644--- a/packages/core/src/TabList/TabList.tsx+++ b/packages/core/src/TabList/TabList.tsx@@ -112,6 +112,24 @@ export interface TabListProps extends Omit<BaseProps<HTMLElement>, 'onChange'> {* @default false*/hasDivider?: boolean;+ /**+ * Bleeds the strip out to its container's content edges.+ *+ * Both halves are computed from the `--container-padding-*` custom+ * properties a padded Layout container publishes. The strip's box is pulled+ * out through the container's inline padding, so a `hasDivider` underline —+ * or the header's own divider, when the strip is docked on it — spans the+ * full content width. The strip then pads back in by whatever that bleed+ * exceeds a stop's own inline padding, so the first and last label still+ * land on the container's content inset rather than 4px short of it.+ *+ * Outside a padded container the properties are unset, the pad-back clamps+ * to zero, and the strip is left exactly as it was. Block-edge docking stays+ * with the surrounding layout because it cannot be detected through nested+ * wrappers without pulling a mid-content strip into its siblings.+ * @default false+ */+ isFullBleed?: boolean;/*** ARIA role for the strip.*@@ -166,6 +184,17 @@ export interface TabListProps extends Omit<BaseProps<HTMLElement>, 'onChange'> {const RING_BLEED = `calc(${focusVars['--focus-outline-width']} + ${focusVars['--focus-outline-offset']})`;const BLEED_VAR = '--_tab-strip-bleed';const BLEED = `var(${BLEED_VAR})`;++/**+ * A stop's own inline padding, restated here because a full-bleed strip has to+ * subtract it: the strip pads back in only the part of the container's padding+ * the stop does not already supply, so the edge label lands on the content+ * inset. Kept in step with `Tab`/`TabMenu`'s `paddingInline` by hand — the+ * import would be circular.+ */+const STOP_INLINE_PADDING = spacingVars['--spacing-3'];+const EDGE_PAD_START = `max(var(--container-padding-inline-start, 0px) - ${STOP_INLINE_PADDING}, 0px)`;+const EDGE_PAD_END = `max(var(--container-padding-inline-end, 0px) - ${STOP_INLINE_PADDING}, 0px)`;const INDICATOR_BLEED = 'calc(-1 * var(--_tab-indicator-bottom, -1px))';const BLOCK_END_BLEED = `max(${BLEED}, ${INDICATOR_BLEED})`;@@ -258,6 +287,15 @@ const styles = stylex.create({},transitionTimingFunction: easeVars['--ease-standard'],},+ // Put back the part of the bleed a stop's own inline padding does not+ // already supply, so the first and last label land on the container's+ // content inset while their boxes still hang out over it. Applied after+ // `stripScroll` because both write the strip's inline padding; the ring+ // bleed is carried through so the negative margin there still cancels it.+ fullBleedStrip: {+ paddingInlineStart: `calc(var(${BLEED_VAR}, 0px) + ${EDGE_PAD_START})`,+ paddingInlineEnd: `calc(var(${BLEED_VAR}, 0px) + ${EDGE_PAD_END})`,+ },fadeStart: {maskImage: {default: FADE_FROM_START,@@ -309,6 +347,16 @@ const styles = stylex.create({arrowEnd: {insetInlineEnd: 0,},+ fullBleed: {+ // Cancel the container's inline padding so the strip's box reaches its+ // content edges. Same spelling as Divider's `isFullBleed`.+ marginInlineStart: 'calc(-1 * var(--container-padding-inline-start, 0px))',+ marginInlineEnd: 'calc(-1 * var(--container-padding-inline-end, 0px))',+ // The `nav` base clamps to 100%, which would pull the widened box back.+ maxWidth: 'none',+ width:+ 'calc(100% + var(--container-padding-inline-start, 0px) + var(--container-padding-inline-end, 0px))',+ },});const arrowSizeStyles = stylex.create({@@ -349,6 +397,7 @@ export function TabList({size: sizeProp,layout = 'hug',hasDivider = false,+ isFullBleed = false,role,overflow = 'auto',xstyle,@@ -624,6 +673,7 @@ export function TabList({styles.nav,layout === 'fill' && styles.fill,hasDivider && styles.divider,+ isFullBleed && styles.fullBleed,xstyle,),className,@@ -640,6 +690,7 @@ export function TabList({stylex.props(styles.strip,hasScroll && styles.stripScroll,+ isFullBleed && styles.fullBleedStrip,fadeStyle,),)}>