An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file ChatLayout.tsx
* @input Uses React, StyleX, theme tokens, useChatStreamScroll, useChatNewMessages,
* useChatKeyboard, the pooled resize observer
* @output Exports ChatLayout component and ChatLayoutProps
* @position Layout shell for full chat interfaces — messages in page flow, composer fixed to bottom
*
* Structural layout only — scroll behavior is delegated to hooks.
* Provides the scroll container ref and content ref, renders the
* scroll-to-bottom button, frosted glass dock, and message area.
*
* Layout contract: the root is a flex column. The message area flexes
* (grow 1, shrink 0) to fill the space the dock doesn't need; the sticky
* dock keeps its natural height in flow. Short content therefore fills
* exactly 100% with no overflow, and long content grows past the root so
* self-scroll mode scrolls (#2573). In external-scrollRef mode the dock
* is position: fixed (out of flow) and the message area fills the root.
* There the message area's end padding also holds the dock's height, which
* the pooled resize observer reports. So the newest message rests above the
* dock at the scroll's end, as it does in self-scroll mode.
*
* Software keyboard (useChatKeyboard): the dock rests above the keyboard.
* The message area's end padding lets the newest message scroll above it.
* Both follow the keyboard height, and the keyboard's own motion rides on
* top. Every route into the composer's text skips Safari's page scroll.
*
* Density (compact/balanced/spacious) is controlled via a prop with
* 'balanced' as the default. No JS measurement or ResizeObserver needed.
* The container-type on root enables container queries in child components.
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/Chat/index.ts (exports)
* - /apps/storybook/stories/ChatLayout.stories.tsx
* - /packages/cli/assets/templates/blocks/components/ChatLayout/ (block examples)
*/
import {type ReactNode, useCallback, useMemo, useRef, useState} from 'react';
import * as stylex from '@stylexjs/stylex';
import {focusVars, spacingVars} from '../theme/tokens.stylex';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import type {BaseProps} from '../BaseProps';
import {mergeProps} from '../utils';
import {useChatStreamScroll} from './useChatStreamScroll';
import {useChatNewMessages} from './useChatNewMessages';
import {useChatKeyboard} from './useChatKeyboard';
import {ChatLayoutScrollButton} from './ChatLayoutScrollButton';
import {ChatLayoutContext} from './ChatContext';
import {KeyboardSurfaceContext} from './keyboardSurface';
import {themeProps} from '../utils/themeProps';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {observeResize} from '../utils/sharedResizeObserver';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Chat/ChatLayout.generated';
registerEnglishFallback(english);
// =============================================================================
// Types
// =============================================================================
type Density = 'compact' | 'balanced' | 'spacious';
export interface ChatLayoutProps extends BaseProps<HTMLDivElement> {
/** Ref forwarded to the root element. */
ref?: React.Ref<HTMLDivElement>;
/**
* Message content — flows naturally in the page, scrolls with the page.
* Typically ChatMessageList with ChatMessage children.
*/
children: ReactNode;
/**
* Composer element — fixed to the bottom with a frosted glass dock.
* Typically ChatComposer.
*/
composer: ReactNode;
/**
* Content shown when children is empty.
*/
emptyState?: ReactNode;
/**
* Scroll-to-bottom button rendered above the composer in the dock.
* Defaults to ChatLayoutScrollButton with useChatStreamScroll.
* Pass a custom ReactNode to override, or `null` to hide.
*/
scrollButton?: ReactNode | null;
/**
* External scroll container ref. When provided, auto-scroll and
* scroll-to-bottom target this element instead of the layout root.
*
* @example
* ```
* const scrollRef = useRef(document.documentElement);
* <ChatLayout scrollRef={scrollRef} composer={...}>...</ChatLayout>
* ```
*
* When omitted, the layout root itself is the scroll container.
*/
scrollRef?: React.RefObject<HTMLElement | null>;
/**
* Layout density. Controls spacing, max-width, and blur layer sizing.
*
* @default 'balanced'
*/
density?: Density;
}
// =============================================================================
// Styles
// =============================================================================
const styles = stylex.create({
root: {
position: 'relative',
containerType: 'inline-size',
minHeight: 0,
flex: 1,
// Flex column so the sticky dock's natural height is part of the 100%:
// messageArea flexes to fill the leftover space instead of forcing
// minHeight: 100% on its own. Without this, the in-flow sticky dock
// adds its full height on top of the 100% message area and the root
// always overflows by exactly the dock height (#2573).
display: 'flex',
flexDirection: 'column',
},
rootScrollable: {
overflowY: 'auto',
overflowX: 'hidden',
},
messageArea: {
display: 'flex',
flexDirection: 'column',
marginInline: 'auto',
// Fill the space the dock doesn't need (grow), but never shrink below
// content height — long content must overflow the root so it scrolls.
flexGrow: 1,
flexShrink: 0,
flexBasis: 'auto',
paddingBlockEnd: spacingVars['--spacing-6'],
width: '100%',
maxWidth: '100%',
paddingInline: 0,
},
// The end padding grows by the part of the keyboard over the dock and, for
// a fixed dock, by the dock's height. So the newest message can scroll
// above the composer, with no element added for it.
messageAreaEndRoom: (room: number) => ({
paddingBlockEnd: `calc(${spacingVars['--spacing-6']} + ${room}px)`,
}),
emptyState: {
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
flex: 1,
minHeight: 200,
},
// --- Dock container ---
dockContainer: {
bottom: 0,
insetInlineStart: 0,
insetInlineEnd: 0,
zIndex: 0,
isolation: 'isolate',
pointerEvents: 'none',
// Keep the sticky dock at its natural height as a flex item.
// (Inert in fixed mode — position: fixed takes it out of flex layout.)
flexShrink: 0,
},
dockContainerFixed: {
position: 'fixed',
},
dockContainerSticky: {
position: 'sticky',
},
// Rests the dock above the part of the keyboard that covers it
// (useChatKeyboard's lift).
dockLift: (lift: number) => ({
bottom: lift,
}),
blurLayer: {
position: 'absolute',
bottom: 0,
insetInlineStart: 0,
insetInlineEnd: 0,
pointerEvents: 'none',
backdropFilter: 'blur(12px)',
WebkitBackdropFilter: 'blur(12px)',
height: 100,
maskImage: 'linear-gradient(to bottom, transparent, black 36px)',
WebkitMaskImage: 'linear-gradient(to bottom, transparent, black 36px)',
},
dock: {
position: 'relative',
zIndex: 1,
pointerEvents: 'auto',
paddingInline: spacingVars['--spacing-3'],
paddingBlockEnd: spacingVars['--spacing-3'],
},
// The ring Done's park shows after typing, inside the dock's edge, which can
// meet the viewport's.
dockFocusRing: {
outlineOffset: {
default: null,
':focus-visible': `calc(-1 * ${focusVars['--focus-outline-width']})`,
},
},
dockInner: {
marginInline: 'auto',
width: '100%',
maxWidth: '100%',
},
// --- Forced density overrides (disable container queries) ---
messageAreaCompact: {
maxWidth: '100%',
paddingInline: 0,
},
messageAreaBalanced: {
maxWidth: '100%',
paddingInline: 0,
},
messageAreaSpacious: {
maxWidth: 800,
paddingInline: spacingVars['--spacing-4'],
},
blurLayerCompact: {
height: 80,
maskImage: 'linear-gradient(to bottom, transparent, black 24px)',
WebkitMaskImage: 'linear-gradient(to bottom, transparent, black 24px)',
},
blurLayerBalanced: {
height: 100,
maskImage: 'linear-gradient(to bottom, transparent, black 36px)',
WebkitMaskImage: 'linear-gradient(to bottom, transparent, black 36px)',
},
blurLayerSpacious: {
height: 120,
maskImage: 'linear-gradient(to bottom, transparent, black 48px)',
WebkitMaskImage: 'linear-gradient(to bottom, transparent, black 48px)',
},
dockCompact: {
paddingInline: spacingVars['--spacing-2'],
paddingBlockEnd: spacingVars['--spacing-2'],
},
dockBalanced: {
paddingInline: spacingVars['--spacing-3'],
paddingBlockEnd: spacingVars['--spacing-3'],
},
dockSpacious: {
paddingInline: spacingVars['--spacing-4'],
paddingBlockEnd: spacingVars['--spacing-3'],
},
dockInnerCompact: {
maxWidth: '100%',
},
dockInnerBalanced: {
maxWidth: '100%',
},
dockInnerSpacious: {
maxWidth: 800,
},
});
// =============================================================================
// Helpers
// =============================================================================
function hasVisibleContent(children: ReactNode): boolean {
// eslint-disable-next-line @astryx/no-nullish-jsx-guard -- component:ChatLayout FR5 names exactly null, undefined, false and an empty array as empty children; '' and true are not
if (children == null || children === false) {
return false;
}
if (Array.isArray(children) && children.length === 0) {
return false;
}
return true;
}
// =============================================================================
// Component
// =============================================================================
/**
* Layout shell for a full chat interface: messages in page flow, composer
* docked to the bottom behind a frosted glass layer, with auto-scroll and a
* scroll-to-bottom button wired in.
*
* @example
* ```
* <ChatLayout
* density="spacious"
* composer={<ChatComposer onSubmit={send} />}
* emptyState={<EmptyState title="No messages yet" />}>
* <ChatMessageList>
* <ChatMessage sender="assistant">
* <ChatMessageBubble>How can I help?</ChatMessageBubble>
* </ChatMessage>
* </ChatMessageList>
* </ChatLayout>
* ```
*/
export function ChatLayout({
children,
composer,
density = 'balanced',
emptyState,
scrollButton,
scrollRef: externalScrollRef,
xstyle,
className,
style,
'data-testid': testId,
ref,
...rest
}: ChatLayoutProps) {
const t = useComponentTranslator();
const rootRef = useRef<HTMLDivElement>(null);
const scrollContainerRef = externalScrollRef ?? rootRef;
const isSelfScrolling = !externalScrollRef;
// --- Default scroll behavior ---
const scroll = useChatStreamScroll({scrollRef: scrollContainerRef});
const newMsgs = useChatNewMessages({
isLocked: scroll.isLocked,
onResize: scroll.scrollIfLocked,
});
// --- Software keyboard ---
const keyboard = useChatKeyboard({
rootRef,
scrollRef: scrollContainerRef,
isSelfScrolling,
scrollToBottom: scroll.scrollToBottom,
});
// --- Fixed dock's height ---
// A fixed dock is out of flow, so the message area makes room for it. The
// room is the dock's border-box height, as the pooled observer reports it.
// The padding changes only the message area, so it never resizes the dock.
// React calls the returned unsubscribe when the dock detaches or the
// scroll mode changes.
const [dockHeight, setDockHeight] = useState(0);
const observeDock = useCallback(
(dock: HTMLDivElement | null) => {
if (dock == null || isSelfScrolling) {
return undefined;
}
return observeResize(dock, entry => {
// The pooled observer's first call carries no size. The mount reads
// the dock once, so the first paint has the room.
const height =
entry.borderBoxSize?.[0]?.blockSize ??
dock.getBoundingClientRect().height;
setDockHeight(Math.round(height));
});
},
[isSelfScrolling],
);
const dockRef = useMergedRefs(keyboard.dockRef, observeDock);
const endRoom = keyboard.lift + (isSelfScrolling ? 0 : dockHeight);
const defaultScrollButton = (
<ChatLayoutScrollButton
isVisible={scroll.isScrolledUp || newMsgs.hasNewMessages}
label={
newMsgs.hasNewMessages ? t('@astryx.chatLayout.newMessages') : undefined
}
onClick={() => {
newMsgs.dismiss();
scroll.scrollToBottom();
}}
/>
);
// --- Layout context ---
const layoutContext = useMemo(
() => ({scrollContainerRef, contentRef: newMsgs.contentRef}),
[scrollContainerRef, newMsgs.contentRef],
);
// --- Derived styles ---
const showEmpty = !hasVisibleContent(children);
const densityStyles = {
compact: {
messageArea: styles.messageAreaCompact,
blurLayer: styles.blurLayerCompact,
dock: styles.dockCompact,
dockInner: styles.dockInnerCompact,
},
balanced: {
messageArea: styles.messageAreaBalanced,
blurLayer: styles.blurLayerBalanced,
dock: styles.dockBalanced,
dockInner: styles.dockInnerBalanced,
},
spacious: {
messageArea: styles.messageAreaSpacious,
blurLayer: styles.blurLayerSpacious,
dock: styles.dockSpacious,
dockInner: styles.dockInnerSpacious,
},
} as const;
const currentDensity = densityStyles[density];
return (
<ChatLayoutContext value={layoutContext}>
<div
{...rest}
ref={useMergedRefs(ref, rootRef)}
data-testid={testId}
{...mergeProps(
themeProps('chat-layout', {density}),
stylex.props(
styles.root,
isSelfScrolling && styles.rootScrollable,
xstyle,
),
className,
style,
)}>
{/* Message area */}
<div
ref={keyboard.messagesRef}
{...stylex.props(
styles.messageArea,
currentDensity.messageArea,
endRoom > 0 && styles.messageAreaEndRoom(endRoom),
)}>
{showEmpty && emptyState ? (
<div {...stylex.props(styles.emptyState)}>{emptyState}</div>
) : (
children
)}
</div>
{/* Dock container — sticky/fixed, holds blur + scroll button + composer */}
<div
ref={dockRef}
{...stylex.props(
styles.dockContainer,
isSelfScrolling
? styles.dockContainerSticky
: styles.dockContainerFixed,
keyboard.lift > 0 && styles.dockLift(keyboard.lift),
)}>
{/* Scroll-to-bottom button */}
{scrollButton === undefined ? defaultScrollButton : scrollButton}
{/* Frosted glass layer */}
<div {...stylex.props(styles.blurLayer, currentDensity.blurLayer)} />
{/* The composer's region. Under a finger in a top-level page,
useChatKeyboard makes it a group with no name, where focus rests
after the keyboard's Done. Elsewhere it is a plain container. */}
<KeyboardSurfaceContext value={true}>
<div
ref={keyboard.composerRef}
{...stylex.props(
focusOutlineStyles.focusVisible,
styles.dock,
currentDensity.dock,
styles.dockFocusRing,
)}>
<div
{...stylex.props(styles.dockInner, currentDensity.dockInner)}>
{composer}
</div>
</div>
</KeyboardSurfaceContext>
</div>
</div>
</ChatLayoutContext>
);
}
ChatLayout.displayName = 'ChatLayout';