Skip to content

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

TypeScript

feat(Table): container bleed — auto edge-to-edge in Cards and Layout areas (#1130)

Cindy Zhang5cab3663bc9f
diff --git a/apps/storybook/stories/Table.stories.tsx b/apps/storybook/stories/Table.stories.tsx
index b084f83d76..fb8fb2b743 100644
--- a/apps/storybook/stories/Table.stories.tsx
+++ b/apps/storybook/stories/Table.stories.tsx
@@ -1,4 +1,5 @@
import type {Meta, StoryObj} from '@storybook/react';
+import * as stylex from '@stylexjs/stylex';
import {
XDSTable,
XDSTableRow,
@@ -7,12 +8,29 @@ import {
pixel,
} from '@xds/core/Table';
import type {XDSTableColumn} from '@xds/core/Table';
+import {XDSCard} from '@xds/core/Card';
+import {XDSSection} from '@xds/core/Section';
+import {
+ XDSLayout,
+ XDSLayoutHeader,
+ XDSLayoutContent,
+ XDSLayoutFooter,
+ XDSVStack,
+ XDSHStack,
+} from '@xds/core/Layout';
+import {XDSHeading} from '@xds/core/Text';
+import {XDSButton} from '@xds/core/Button';
import {
colorDefaults,
spacingDefaults,
radiusDefaults,
textSizeDefaults,
} from '@xds/core/theme';
+import {
+ colorVars,
+ spacingVars,
+ typographyVars,
+} from '@xds/core/theme/tokens.stylex';
// =============================================================================
// Sample Data
@@ -376,3 +394,237 @@ export const OverflowBehavior: Story = {
);
},
};
+
+// =============================================================================
+// Container Bleed — Table inside Card, Section, and Layout
+// =============================================================================
+
+const containerStoryStyles = stylex.create({
+ pageWrapper: {
+ backgroundColor: colorVars['--color-background-body'],
+ padding: spacingVars['--spacing-6'],
+ },
+ storyWrapper: {
+ display: 'flex',
+ gap: spacingVars['--spacing-6'],
+ flexWrap: 'wrap',
+ alignItems: 'start',
+ },
+ text: {
+ fontFamily: typographyVars['--font-family-body'],
+ color: colorVars['--color-text-secondary'],
+ fontSize: 14,
+ margin: 0,
+ },
+ heading: {
+ margin: `0 0 ${spacingVars['--spacing-2']} 0`,
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: 14,
+ color: colorVars['--color-text-secondary'],
+ },
+});
+
+const simpleColumns: XDSTableColumn<User>[] = [
+ {key: 'name', header: 'Name'},
+ {key: 'role', header: 'Role'},
+ {key: 'email', header: 'Email'},
+];
+
+/**
+ * Table inside a Card automatically bleeds to the card edges.
+ * The first column's start padding and last column's end padding
+ * align with the card's content padding, so text lines up with
+ * other content in the card.
+ */
+export const InCard: Story = {
+ decorators: [
+ Story => (
+ <div {...stylex.props(containerStoryStyles.pageWrapper)}>
+ <Story />
+ </div>
+ ),
+ ],
+ render: () => (
+ <div {...stylex.props(containerStoryStyles.storyWrapper)}>
+ <div>
+ <h4 {...stylex.props(containerStoryStyles.heading)}>
+ Table in Card (auto bleed)
+ </h4>
+ <XDSCard width={480}>
+ <XDSTable data={users.slice(0, 4)} columns={simpleColumns} />
+ </XDSCard>
+ </div>
+ <div>
+ <h4 {...stylex.props(containerStoryStyles.heading)}>
+ Before: Card padding={0} (old pattern)
+ </h4>
+ <XDSCard width={480} padding={0}>
+ <XDSTable data={users.slice(0, 4)} columns={simpleColumns} />
+ </XDSCard>
+ </div>
+ </div>
+ ),
+};
+
+/**
+ * Card with a heading above the table. The table bleeds edge-to-edge
+ * while the heading respects the card's content padding — text in the
+ * first column aligns with the heading.
+ */
+export const InCardWithHeading: Story = {
+ decorators: [
+ Story => (
+ <div {...stylex.props(containerStoryStyles.pageWrapper)}>
+ <Story />
+ </div>
+ ),
+ ],
+ render: () => (
+ <XDSCard width={520}>
+ <XDSVStack gap={3}>
+ <XDSHeading level={3}>Team Members</XDSHeading>
+ <XDSTable data={users.slice(0, 4)} columns={simpleColumns} hasHover />
+ </XDSVStack>
+ </XDSCard>
+ ),
+};
+
+/**
+ * Table inside a Card with XDSLayout — header, content with table, footer.
+ * The table bleeds within the layout content area while header/footer
+ * retain their own padding.
+ */
+export const InCardWithLayout: Story = {
+ decorators: [
+ Story => (
+ <div {...stylex.props(containerStoryStyles.pageWrapper)}>
+ <Story />
+ </div>
+ ),
+ ],
+ render: () => (
+ <XDSCard width={560}>
+ <XDSLayout
+ header={
+ <XDSLayoutHeader hasDivider>
+ <XDSHeading level={3}>User Directory</XDSHeading>
+ </XDSLayoutHeader>
+ }
+ content={
+ <XDSLayoutContent>
+ <XDSTable data={users} columns={simpleColumns} hasHover isStriped />
+ </XDSLayoutContent>
+ }
+ footer={
+ <XDSLayoutFooter hasDivider>
+ <XDSHStack gap={2} hAlign="end">
+ <XDSButton label="Export" variant="secondary">
+ Export
+ </XDSButton>
+ <XDSButton label="Add User" variant="primary">
+ Add User
+ </XDSButton>
+ </XDSHStack>
+ </XDSLayoutFooter>
+ }
+ />
+ </XDSCard>
+ ),
+};
+
+/**
+ * Table inside a Section with wash background. The section escapes
+ * the card padding, and the table bleeds within the section.
+ */
+export const InCardWithSection: Story = {
+ decorators: [
+ Story => (
+ <div {...stylex.props(containerStoryStyles.pageWrapper)}>
+ <Story />
+ </div>
+ ),
+ ],
+ render: () => (
+ <XDSCard width={520}>
+ <XDSVStack gap={3}>
+ <XDSHeading level={3}>Dashboard</XDSHeading>
+ <p {...stylex.props(containerStoryStyles.text)}>
+ The table below is in a wash section for visual separation.
+ </p>
+ </XDSVStack>
+ <XDSSection variant="wash">
+ <XDSTable
+ data={users.slice(0, 3)}
+ columns={simpleColumns}
+ density="compact"
+ />
+ </XDSSection>
+ </XDSCard>
+ ),
+};
+
+/**
+ * Compares all three density levels inside cards to show how
+ * the edge padding adapts — it always matches the container padding,
+ * with a minimum of 8px even for compact tables.
+ */
+export const InCardDensities: Story = {
+ decorators: [
+ Story => (
+ <div {...stylex.props(containerStoryStyles.pageWrapper)}>
+ <Story />
+ </div>
+ ),
+ ],
+ render: () => (
+ <div {...stylex.props(containerStoryStyles.storyWrapper)}>
+ {(['compact', 'balanced', 'spacious'] as const).map(density => (
+ <div key={density}>
+ <h4 {...stylex.props(containerStoryStyles.heading)}>{density}</h4>
+ <XDSCard width={400}>
+ <XDSVStack gap={2}>
+ <XDSHeading level={4}>Team</XDSHeading>
+ <XDSTable
+ data={users.slice(0, 3)}
+ columns={simpleColumns}
+ density={density}
+ />
+ </XDSVStack>
+ </XDSCard>
+ </div>
+ ))}
+ </div>
+ ),
+};
+
+/**
+ * Standalone table (no container) — behaves normally with
+ * density-based cell padding. No bleed, no edge compensation.
+ */
+export const StandaloneVsContainer: Story = {
+ decorators: [
+ Story => (
+ <div {...stylex.props(containerStoryStyles.pageWrapper)}>
+ <Story />
+ </div>
+ ),
+ ],
+ render: () => (
+ <div {...stylex.props(containerStoryStyles.storyWrapper)}>
+ <div>
+ <h4 {...stylex.props(containerStoryStyles.heading)}>
+ Standalone (no container)
+ </h4>
+ <div style={{width: 400}}>
+ <XDSTable data={users.slice(0, 3)} columns={simpleColumns} />
+ </div>
+ </div>
+ <div>
+ <h4 {...stylex.props(containerStoryStyles.heading)}>Inside Card</h4>
+ <XDSCard width={400}>
+ <XDSTable data={users.slice(0, 3)} columns={simpleColumns} />
+ </XDSCard>
+ </div>
+ </div>
+ ),
+};
diff --git a/packages/core/src/Table/XDSTable.tsx b/packages/core/src/Table/XDSTable.tsx
index 49f0828b69..eaaaa9f661 100644
--- a/packages/core/src/Table/XDSTable.tsx
+++ b/packages/core/src/Table/XDSTable.tsx
@@ -13,7 +13,6 @@
* - /apps/storybook/stories/Table.stories.tsx (storybook stories)
*/
-
import {useMemo, type ReactElement, type Ref} from 'react';
import * as stylex from '@stylexjs/stylex';
import {colorVars} from '../theme/tokens.stylex';
@@ -76,6 +75,27 @@ const tableStyles = stylex.create({
fontFamily: 'inherit',
color: colorVars['--color-text-primary'],
},
+ /**
+ * Container bleed: table escapes parent container padding horizontally
+ * so rows span edge-to-edge inside Cards and Layout areas.
+ * Uses --container-padding-inline set by Card/Section/Layout containers.
+ *
+ * Vertical bleed uses :first-child / :last-child to escape container
+ * block padding at the edges — same pattern as XDSSection.
+ */
+ containerBleed: {
+ marginInlineStart: 'calc(-1 * var(--container-padding-inline, 0px))',
+ marginInlineEnd: 'calc(-1 * var(--container-padding-inline, 0px))',
+ width: 'calc(100% + 2 * var(--container-padding-inline, 0px))',
+ marginTop: {
+ default: null,
+ ':first-child': 'calc(-1 * var(--container-padding, 0px))',
+ },
+ marginBottom: {
+ default: null,
+ ':last-child': 'calc(-1 * var(--container-padding, 0px))',
+ },
+ },
});
// =============================================================================
@@ -89,7 +109,7 @@ function buildTableStylePlugin<
transformTable(props: TableRenderProps): TableRenderProps {
return {
...props,
- styles: [...props.styles, tableStyles.base],
+ styles: [...props.styles, tableStyles.base, tableStyles.containerBleed],
};
},
};
diff --git a/packages/core/src/Table/XDSTableCell.tsx b/packages/core/src/Table/XDSTableCell.tsx
index d2740af141..4cfd351fa3 100644
--- a/packages/core/src/Table/XDSTableCell.tsx
+++ b/packages/core/src/Table/XDSTableCell.tsx
@@ -21,7 +21,7 @@ import {
typeScaleVars,
} from '../theme/tokens.stylex';
import type {StyleXStyles} from '../theme/types';
-import {overflowStyles} from './table.stylex';
+import {overflowStyles, containerEdgeStyles} from './table.stylex';
import {
useTableContext,
buildDividerStyles,
@@ -121,6 +121,7 @@ export function XDSTableCell({
const cellStyles: StyleXStyles[] = [
densityStyles[ctx.density],
overflowStyles.cell,
+ containerEdgeStyles[ctx.density],
...buildDividerStyles(ctx, dividerRowStyles.cell, dividerColumnStyles.cell),
];
diff --git a/packages/core/src/Table/XDSTableHeaderCell.tsx b/packages/core/src/Table/XDSTableHeaderCell.tsx
index 511d09658e..ab23391e90 100644
--- a/packages/core/src/Table/XDSTableHeaderCell.tsx
+++ b/packages/core/src/Table/XDSTableHeaderCell.tsx
@@ -22,7 +22,7 @@ import {
borderVars,
} from '../theme/tokens.stylex';
import type {StyleXStyles} from '../theme/types';
-import {overflowStyles} from './table.stylex';
+import {overflowStyles, containerEdgeStyles} from './table.stylex';
import {
useTableContext,
buildDividerStyles,
@@ -145,6 +145,7 @@ export function XDSTableHeaderCell({
densityStyles[ctx.density],
headerDividerStyles.cell,
overflowStyles.cell,
+ containerEdgeStyles[ctx.density],
];
// Only add column dividers from the shared builder
diff --git a/packages/core/src/Table/table.stylex.ts b/packages/core/src/Table/table.stylex.ts
index f395abaa7a..955f93d139 100644
--- a/packages/core/src/Table/table.stylex.ts
+++ b/packages/core/src/Table/table.stylex.ts
@@ -3,9 +3,14 @@
* @input StyleX, theme tokens
* @output Shared table styles used by XDSTableCell and XDSTableHeaderCell
* @position Utility styles; consumed by cell components
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/XDSTableCell.tsx
+ * - /packages/core/src/Table/XDSTableHeaderCell.tsx
*/
import * as stylex from '@stylexjs/stylex';
+import {spacingVars} from '../theme/tokens.stylex';
/**
* Overflow truncation for table cells.
@@ -23,3 +28,49 @@ export const overflowStyles = stylex.create({
maxWidth: '0',
},
});
+
+/**
+ * Container edge compensation for table cells.
+ *
+ * When a table is inside a Card, Section, or Layout area, the table
+ * element applies negative inline margins to bleed edge-to-edge
+ * (see XDSTable.tsx containerBleed style). These styles ensure the
+ * first and last columns' outer padding aligns with the container's
+ * content inset, with a minimum of --spacing-2 (8px).
+ *
+ * Each density variant uses its own paddingInline as the fallback,
+ * so standalone tables (where --container-padding-inline is unset)
+ * keep their normal density-based cell padding unchanged.
+ */
+export const containerEdgeStyles = stylex.create({
+ compact: {
+ paddingInlineStart: {
+ default: null,
+ ':first-child': `max(var(--container-padding-inline, ${spacingVars['--spacing-2']}), ${spacingVars['--spacing-2']})`,
+ },
+ paddingInlineEnd: {
+ default: null,
+ ':last-child': `max(var(--container-padding-inline, ${spacingVars['--spacing-2']}), ${spacingVars['--spacing-2']})`,
+ },
+ },
+ balanced: {
+ paddingInlineStart: {
+ default: null,
+ ':first-child': `max(var(--container-padding-inline, ${spacingVars['--spacing-3']}), ${spacingVars['--spacing-2']})`,
+ },
+ paddingInlineEnd: {
+ default: null,
+ ':last-child': `max(var(--container-padding-inline, ${spacingVars['--spacing-3']}), ${spacingVars['--spacing-2']})`,
+ },
+ },
+ spacious: {
+ paddingInlineStart: {
+ default: null,
+ ':first-child': `max(var(--container-padding-inline, ${spacingVars['--spacing-4']}), ${spacingVars['--spacing-2']})`,
+ },
+ paddingInlineEnd: {
+ default: null,
+ ':last-child': `max(var(--container-padding-inline, ${spacingVars['--spacing-4']}), ${spacingVars['--spacing-2']})`,
+ },
+ },
+});