Skip to content

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

TypeScript

feat(Layout): add defaultHasDividers context for container-controlled dividers (#969)

Cindy Zhang78d76df2fe31
diff --git a/apps/storybook/stories/Dialog.stories.tsx b/apps/storybook/stories/Dialog.stories.tsx
index 79b89fae73..11aa19c86a 100644
--- a/apps/storybook/stories/Dialog.stories.tsx
+++ b/apps/storybook/stories/Dialog.stories.tsx
@@ -60,7 +60,7 @@ function BasicModalExample() {
<>
<XDSButton
label="Open Modal"
- variant="primary"
+ variant="secondary"
onClick={() => setIsOpen(true)}
/>
<XDSDialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>
@@ -81,7 +81,7 @@ function BasicModalExample() {
</XDSLayoutContent>
}
footer={
- <XDSLayoutFooter hasDivider>
+ <XDSLayoutFooter>
<XDSHStack gap={2} hAlign="end">
<XDSButton
label="Cancel"
@@ -137,7 +137,7 @@ function SubtitleModalExample() {
</XDSLayoutContent>
}
footer={
- <XDSLayoutFooter hasDivider>
+ <XDSLayoutFooter>
<XDSHStack gap={2} hAlign="end">
<XDSButton
label="Cancel"
@@ -194,7 +194,7 @@ function WideModalExample() {
</XDSLayoutContent>
}
footer={
- <XDSLayoutFooter hasDivider>
+ <XDSLayoutFooter>
<XDSHStack hAlign="end">
<XDSButton
label="Close"
@@ -258,7 +258,7 @@ function FullscreenModalExample() {
</XDSLayoutContent>
}
footer={
- <XDSLayoutFooter hasDivider>
+ <XDSLayoutFooter>
<XDSHStack hAlign="end">
<XDSButton
label="Close"
@@ -317,7 +317,7 @@ function RequiredModalExample() {
</XDSLayoutContent>
}
footer={
- <XDSLayoutFooter hasDivider>
+ <XDSLayoutFooter>
<XDSHStack hAlign="end">
<XDSButton
label="I Accept"
@@ -372,7 +372,7 @@ function FormModalExample() {
</XDSLayoutContent>
}
footer={
- <XDSLayoutFooter hasDivider>
+ <XDSLayoutFooter>
<XDSHStack gap={2} hAlign="end">
<XDSButton
label="Cancel"
@@ -431,7 +431,7 @@ function InfoModalExample() {
</XDSLayoutContent>
}
footer={
- <XDSLayoutFooter hasDivider>
+ <XDSLayoutFooter>
<XDSHStack hAlign="end">
<XDSButton
label="Got it"
@@ -485,7 +485,7 @@ function PositionedModalExample() {
</XDSLayoutContent>
}
footer={
- <XDSLayoutFooter hasDivider>
+ <XDSLayoutFooter>
<XDSHStack hAlign="end">
<XDSButton
label="Close"
@@ -547,7 +547,7 @@ function ScrollingModalExample() {
</XDSLayoutContent>
}
footer={
- <XDSLayoutFooter hasDivider>
+ <XDSLayoutFooter>
<XDSHStack gap={2} hAlign="end">
<XDSButton
label="Decline"
@@ -617,7 +617,7 @@ function ConfirmationModalExample() {
</XDSLayoutContent>
}
footer={
- <XDSLayoutFooter hasDivider>
+ <XDSLayoutFooter>
<XDSHStack gap={2} hAlign="end">
<XDSButton
label="Cancel"
diff --git a/packages/core/src/Dialog/XDSDialogHeader.test.tsx b/packages/core/src/Dialog/XDSDialogHeader.test.tsx
index 98f555388b..d8c709261a 100644
--- a/packages/core/src/Dialog/XDSDialogHeader.test.tsx
+++ b/packages/core/src/Dialog/XDSDialogHeader.test.tsx
@@ -11,6 +11,7 @@ import {describe, it, expect, vi} from 'vitest';
import {render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {XDSDialogHeader} from './XDSDialogHeader';
+import {XDSLayoutDividerContext} from '../Layout/XDSLayoutDividerContext';
describe('XDSDialogHeader', () => {
it('renders the title', () => {
@@ -69,11 +70,57 @@ describe('XDSDialogHeader', () => {
expect(handleHide).toHaveBeenCalledTimes(1);
});
- it('renders with divider by default', () => {
- const {container} = render(<XDSDialogHeader title="Title" />);
- // Check that the header div has divider styles (border-bottom)
- const header = container.firstChild as HTMLElement;
- expect(header).toBeInTheDocument();
+ it('renders without divider by default (no context)', () => {
+ // Without context, hasDivider defaults to false — same classes as explicit hasDivider={false}
+ const {container: noCtx} = render(<XDSDialogHeader title="No ctx" />);
+ const {container: explicitFalse} = render(
+ <XDSDialogHeader title="Explicit false" hasDivider={false} />,
+ );
+ const noCtxHeader = noCtx.firstChild as HTMLElement;
+ const explicitFalseHeader = explicitFalse.firstChild as HTMLElement;
+ expect(noCtxHeader.className).toBe(explicitFalseHeader.className);
+ });
+
+ it('renders with divider when context defaultHasDividers is true', () => {
+ // With context true and no explicit prop, should match explicit hasDivider={true}
+ const {container: ctxTrue} = render(
+ <XDSLayoutDividerContext.Provider value={{defaultHasDividers: true}}>
+ <XDSDialogHeader title="Ctx true" />
+ </XDSLayoutDividerContext.Provider>,
+ );
+ const {container: explicitTrue} = render(
+ <XDSDialogHeader title="Explicit true" hasDivider={true} />,
+ );
+ const ctxHeader = ctxTrue.firstChild as HTMLElement;
+ const explicitHeader = explicitTrue.firstChild as HTMLElement;
+ expect(ctxHeader.className).toBe(explicitHeader.className);
+ });
+
+ it('explicit hasDivider={false} overrides context defaultHasDividers=true', () => {
+ const {container: overridden} = render(
+ <XDSLayoutDividerContext.Provider value={{defaultHasDividers: true}}>
+ <XDSDialogHeader title="Overridden" hasDivider={false} />
+ </XDSLayoutDividerContext.Provider>,
+ );
+ const {container: noDivider} = render(
+ <XDSDialogHeader title="No divider" hasDivider={false} />,
+ );
+ const overriddenHeader = overridden.firstChild as HTMLElement;
+ const noDividerHeader = noDivider.firstChild as HTMLElement;
+ expect(overriddenHeader.className).toBe(noDividerHeader.className);
+ });
+
+ it('explicit hasDivider={true} shows divider without context', () => {
+ // Explicit true should differ from default (no context = false)
+ const {container: withDiv} = render(
+ <XDSDialogHeader title="With div" hasDivider={true} />,
+ );
+ const {container: withoutDiv} = render(
+ <XDSDialogHeader title="Without div" hasDivider={false} />,
+ );
+ const withDivHeader = withDiv.firstChild as HTMLElement;
+ const withoutDivHeader = withoutDiv.firstChild as HTMLElement;
+ expect(withDivHeader.className).not.toBe(withoutDivHeader.className);
});
it('renders additional endContent', () => {
diff --git a/packages/core/src/Dialog/XDSDialogHeader.tsx b/packages/core/src/Dialog/XDSDialogHeader.tsx
index fde2ca175c..b796b9cc86 100644
--- a/packages/core/src/Dialog/XDSDialogHeader.tsx
+++ b/packages/core/src/Dialog/XDSDialogHeader.tsx
@@ -88,7 +88,7 @@ export interface XDSDialogHeaderProps {
/**
* Adds a themed border at the bottom edge.
* When false, spacing collapse is applied automatically for seamless visual flow.
- * @default true
+ * Defaults to the parent XDSLayout's `defaultHasDividers` context value.
*/
hasDivider?: boolean;
}
@@ -119,7 +119,7 @@ export function XDSDialogHeader({
onOpenChange,
startContent,
endContent,
- hasDivider = true,
+ hasDivider,
ref,
}: XDSDialogHeaderProps) {
const titleRef = useRef<HTMLHeadingElement>(null);
diff --git a/packages/core/src/Layout/XDSLayout.tsx b/packages/core/src/Layout/XDSLayout.tsx
index 28615c8eba..16a2d7db22 100644
--- a/packages/core/src/Layout/XDSLayout.tsx
+++ b/packages/core/src/Layout/XDSLayout.tsx
@@ -19,6 +19,7 @@ import {type ReactNode, useMemo} from 'react';
import * as stylex from '@stylexjs/stylex';
import {XDSLayoutAreaContext, type LayoutArea} from './XDSLayoutAreaContext';
import {XDSLayoutSlotsContext, type LayoutSlots} from './XDSLayoutSlotsContext';
+import {XDSLayoutDividerContext} from './XDSLayoutDividerContext';
import {stack} from '../Stack/stack.stylex';
import {stackItem} from '../Stack/stackItem.stylex';
import {xdsClassName, mergeProps} from '../utils';
@@ -109,6 +110,13 @@ export interface XDSLayoutProps extends Omit<XDSBaseProps, 'content'> {
* Start panel slot (left in LTR, right in RTL).
*/
start?: ReactNode;
+ /**
+ * Default divider visibility for XDSLayoutHeader and XDSLayoutFooter children.
+ * When set, headers/footers that don't explicitly pass `hasDivider` will use this value.
+ * When not set, nested layouts inherit from their parent context.
+ */
+ defaultHasDividers?: boolean;
+
/**
* CSS class name(s) appended to the root element.
*/
@@ -187,6 +195,7 @@ function AreaProvider({
*/
export function XDSLayout({
content,
+ defaultHasDividers,
end,
footer,
header,
@@ -200,6 +209,11 @@ export function XDSLayout({
}: XDSLayoutProps) {
const isFill = height === 'fill';
+ const dividerCtxValue = useMemo(
+ () => (defaultHasDividers != null ? {defaultHasDividers} : null),
+ [defaultHasDividers],
+ );
+
// Memoize slots info to avoid unnecessary re-renders
const slotsValue = useMemo<LayoutSlots>(
() => ({
@@ -211,7 +225,7 @@ export function XDSLayout({
[header != null, footer != null, start != null, end != null],
);
- return (
+ const tree = (
<XDSLayoutSlotsContext.Provider value={slotsValue}>
<div
ref={ref}
@@ -227,6 +241,7 @@ export function XDSLayout({
)}>
<div
{...stylex.props(
+ stylex.defaultMarker(),
styles.layoutInner,
...stack({direction: 'vertical'}),
isFill ? styles.fill : styles.auto,
@@ -251,6 +266,16 @@ export function XDSLayout({
</div>
</XDSLayoutSlotsContext.Provider>
);
+
+ if (dividerCtxValue != null) {
+ return (
+ <XDSLayoutDividerContext.Provider value={dividerCtxValue}>
+ {tree}
+ </XDSLayoutDividerContext.Provider>
+ );
+ }
+
+ return tree;
}
XDSLayout.displayName = 'XDSLayout';
diff --git a/packages/core/src/Layout/XDSLayoutContent.tsx b/packages/core/src/Layout/XDSLayoutContent.tsx
index 07f8b40e7b..93b54a87e2 100644
--- a/packages/core/src/Layout/XDSLayoutContent.tsx
+++ b/packages/core/src/Layout/XDSLayoutContent.tsx
@@ -12,7 +12,6 @@
* - /apps/storybook/stories/Layout.stories.tsx
*/
-
import type {AriaRole, ReactNode} from 'react';
import type {XDSBaseProps} from '../XDSBaseProps';
import {useContext} from 'react';
@@ -33,8 +32,18 @@ const styles = stylex.create({
// Default: inner padding on all sides (will be overridden by position-specific styles)
paddingInlineStart: `var(--layout-padding-inner-x, ${spacingVars['--spacing-4']})`,
paddingInlineEnd: `var(--layout-padding-inner-x, ${spacingVars['--spacing-4']})`,
- paddingBlockStart: `var(--layout-padding-inner-y, ${spacingVars['--spacing-4']})`,
- paddingBlockEnd: `var(--layout-padding-inner-y, ${spacingVars['--spacing-4']})`,
+ paddingBlockStart: {
+ default: `var(--layout-padding-inner-y, ${spacingVars['--spacing-4']})`,
+ // When header has no divider, collapse top padding for seamless visual flow
+ [stylex.when.ancestor(':has(> .xds-layout-header:not([data-divider]))')]:
+ 0,
+ },
+ paddingBlockEnd: {
+ default: `var(--layout-padding-inner-y, ${spacingVars['--spacing-4']})`,
+ // When footer has no divider, collapse bottom padding for seamless visual flow
+ [stylex.when.ancestor(':has(> .xds-layout-footer:not([data-divider]))')]:
+ 0,
+ },
},
// When no start panel: outer-x on left edge
noStart: {
diff --git a/packages/core/src/Layout/XDSLayoutDividerContext.ts b/packages/core/src/Layout/XDSLayoutDividerContext.ts
new file mode 100644
index 0000000000..92e0ad75d1
--- /dev/null
+++ b/packages/core/src/Layout/XDSLayoutDividerContext.ts
@@ -0,0 +1,24 @@
+'use client';
+
+/**
+ * @file XDSLayoutDividerContext.ts
+ * @input Uses React createContext
+ * @output Exports XDSLayoutDividerContext and LayoutDividerContextValue type
+ * @position Context for container-controlled default divider visibility;
+ * consumed by XDSLayoutHeader.tsx, XDSLayoutFooter.tsx, provided by XDSLayout.tsx
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Layout/Layout.doc.mjs
+ * - /packages/core/src/Layout/XDSLayout.tsx
+ * - /packages/core/src/Layout/XDSLayoutHeader.tsx
+ * - /packages/core/src/Layout/XDSLayoutFooter.tsx
+ */
+
+import {createContext} from 'react';
+
+export interface LayoutDividerContextValue {
+ defaultHasDividers: boolean;
+}
+
+export const XDSLayoutDividerContext =
+ createContext<LayoutDividerContextValue | null>(null);
diff --git a/packages/core/src/Layout/XDSLayoutFooter.tsx b/packages/core/src/Layout/XDSLayoutFooter.tsx
index cd9d72e031..97c50588f5 100644
--- a/packages/core/src/Layout/XDSLayoutFooter.tsx
+++ b/packages/core/src/Layout/XDSLayoutFooter.tsx
@@ -12,8 +12,9 @@
import type {AriaRole, ReactNode} from 'react';
import type {XDSBaseProps} from '../XDSBaseProps';
-import {} from 'react';
+import {useContext} from 'react';
import * as stylex from '@stylexjs/stylex';
+import {XDSLayoutDividerContext} from './XDSLayoutDividerContext';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
import {xdsClassName, mergeProps} from '../utils';
import type {SpacingStep} from '../utils/types';
@@ -40,10 +41,6 @@ const styles = stylex.create({
borderBlockStartStyle: 'solid',
borderBlockStartColor: colorVars['--color-border'],
},
- // When no divider, collapse spacing to avoid double-padding with content
- collapseTop: {
- marginBlockStart: `calc(-1 * var(--layout-padding-inner-y, ${spacingVars['--spacing-4']}))`,
- },
});
// Dynamic styles for sizing props
@@ -63,6 +60,7 @@ export interface XDSLayoutFooterProps extends XDSBaseProps<HTMLDivElement> {
/**
* Adds a themed border at the top edge.
* When false, spacing collapse is applied automatically for seamless visual flow.
+ * When not set, falls back to the parent XDSLayout's `defaultHasDividers`, then `false`.
* @default false
*/
hasDivider?: boolean;
@@ -112,7 +110,7 @@ export interface XDSLayoutFooterProps extends XDSBaseProps<HTMLDivElement> {
*/
export function XDSLayoutFooter({
children,
- hasDivider = false,
+ hasDivider,
height,
label,
padding,
@@ -123,17 +121,17 @@ export function XDSLayoutFooter({
ref,
...props
}: XDSLayoutFooterProps) {
+ const dividerCtx = useContext(XDSLayoutDividerContext);
+ const resolvedHasDivider =
+ hasDivider ?? dividerCtx?.defaultHasDividers ?? false;
const isZeroPadding = padding === 0;
- // When no divider, collapse spacing for seamless visual flow
- const shouldCollapseSpacing =
- !hasDivider && !isZeroPadding && padding == null;
-
return (
<div
ref={ref as React.Ref<HTMLDivElement>}
role={role}
aria-label={label}
+ data-divider={resolvedHasDivider || undefined}
{...mergeProps(
xdsClassName('layout-footer'),
stylex.props(
@@ -142,8 +140,7 @@ export function XDSLayoutFooter({
isZeroPadding && styles.fullBleed,
padding != null && paddingStyles[padding],
padding != null && containerPaddingInlineVarStyles[padding],
- hasDivider && styles.divider,
- shouldCollapseSpacing && styles.collapseTop,
+ resolvedHasDivider && styles.divider,
xstyle,
),
className,
diff --git a/packages/core/src/Layout/XDSLayoutHeader.tsx b/packages/core/src/Layout/XDSLayoutHeader.tsx
index a02ed6d647..72156aa12d 100644
--- a/packages/core/src/Layout/XDSLayoutHeader.tsx
+++ b/packages/core/src/Layout/XDSLayoutHeader.tsx
@@ -12,8 +12,9 @@
import type {AriaRole, ReactNode} from 'react';
import type {XDSBaseProps} from '../XDSBaseProps';
-import {} from 'react';
+import {useContext} from 'react';
import * as stylex from '@stylexjs/stylex';
+import {XDSLayoutDividerContext} from './XDSLayoutDividerContext';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
import {xdsClassName, mergeProps} from '../utils';
import type {SpacingStep} from '../utils/types';
@@ -40,10 +41,6 @@ const styles = stylex.create({
borderBlockEndStyle: 'solid',
borderBlockEndColor: colorVars['--color-border'],
},
- // When no divider, collapse spacing to avoid double-padding with content
- collapseBottom: {
- marginBlockEnd: `calc(-1 * var(--layout-padding-inner-y, ${spacingVars['--spacing-4']}))`,
- },
});
// Dynamic styles for sizing props
@@ -63,6 +60,7 @@ export interface XDSLayoutHeaderProps extends XDSBaseProps<HTMLDivElement> {
/**
* Adds a themed border at the bottom edge.
* When false, spacing collapse is applied automatically for seamless visual flow.
+ * When not set, falls back to the parent XDSLayout's `defaultHasDividers`, then `false`.
* @default false
*/
hasDivider?: boolean;
@@ -112,7 +110,7 @@ export interface XDSLayoutHeaderProps extends XDSBaseProps<HTMLDivElement> {
*/
export function XDSLayoutHeader({
children,
- hasDivider = false,
+ hasDivider,
height,
label,
padding,
@@ -123,17 +121,17 @@ export function XDSLayoutHeader({
ref,
...props
}: XDSLayoutHeaderProps) {
+ const dividerCtx = useContext(XDSLayoutDividerContext);
+ const resolvedHasDivider =
+ hasDivider ?? dividerCtx?.defaultHasDividers ?? false;
const isZeroPadding = padding === 0;
- // When no divider, collapse spacing for seamless visual flow
- const shouldCollapseSpacing =
- !hasDivider && !isZeroPadding && padding == null;
-
return (
<div
ref={ref as React.Ref<HTMLDivElement>}
role={role}
aria-label={label}
+ data-divider={resolvedHasDivider || undefined}
{...mergeProps(
xdsClassName('layout-header'),
stylex.props(
@@ -142,8 +140,7 @@ export function XDSLayoutHeader({
isZeroPadding && styles.fullBleed,
padding != null && paddingStyles[padding],
padding != null && containerPaddingInlineVarStyles[padding],
- hasDivider && styles.divider,
- shouldCollapseSpacing && styles.collapseBottom,
+ resolvedHasDivider && styles.divider,
xstyle,
),
className,
diff --git a/packages/core/src/Layout/index.ts b/packages/core/src/Layout/index.ts
index 7636053936..724572f21c 100644
--- a/packages/core/src/Layout/index.ts
+++ b/packages/core/src/Layout/index.ts
@@ -75,3 +75,6 @@ export type {XDSLayoutPanelProps} from './XDSLayoutPanel';
export {XDSLayoutAreaContext} from './XDSLayoutAreaContext';
export type {LayoutArea} from './XDSLayoutAreaContext';
+
+export {XDSLayoutDividerContext} from './XDSLayoutDividerContext';
+export type {LayoutDividerContextValue} from './XDSLayoutDividerContext';