Skip to content

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

TypeScript

fix(Chat): rename messageGap prop to gap (#2325)

Cindy Zhang266ea90ff5c2
diff --git a/apps/storybook/stories/Chat.stories.tsx b/apps/storybook/stories/Chat.stories.tsx
index 7efbec68a9..3e05cd8daa 100644
--- a/apps/storybook/stories/Chat.stories.tsx
+++ b/apps/storybook/stories/Chat.stories.tsx
@@ -383,7 +383,7 @@ export const DensityComparison: StoryObj = {
- **Padding** inside bubbles
- **Gap** between child elements
-Use messageGap when top-level rows need different spacing from density.
+Use gap when top-level rows need different spacing from density.
This is the **${density}** density. ${density === 'compact' ? 'Great for sidebars and panels where space is limited.' : density === 'spacious' ? 'Ideal for long-form reading where breathing room helps comprehension.' : 'The default — works well for most full-page chat interfaces.'}`}</XDSMarkdown>
</XDSChatMessage>
@@ -404,11 +404,11 @@ This is the **${density}** density. ${density === 'compact' ? 'Great for sidebar
);
},
};
-export const MessageGapOverride: StoryObj = {
+export const GapOverride: StoryObj = {
name: 'Message Gap Override',
render: () => (
<div style={{height: 420, display: 'flex', flexDirection: 'column'}}>
- <XDSChatMessageList density="compact" messageGap={5}>
+ <XDSChatMessageList density="compact" gap={5}>
<XDSChatMessage sender="assistant">
<XDSChatMessageBubble name="Clio">
Starting the requested change.
diff --git a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.doc.mjs b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.doc.mjs
index 5d91b6434a..5a4c8085a0 100644
--- a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.doc.mjs
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.doc.mjs
@@ -5,7 +5,7 @@ export const doc = {
type: 'block',
exampleFor: 'ChatMessageList',
name: 'ChatMessageList — Density',
- description: 'Side-by-side comparison of compact, balanced, and spacious densities. Use compact in sidebars or panels, balanced for most full-page chat, and spacious for long-form reading. Use messageGap when row spacing needs to differ from density.',
+ description: 'Side-by-side comparison of compact, balanced, and spacious densities. Use compact in sidebars or panels, balanced for most full-page chat, and spacious for long-form reading. Use gap when row spacing needs to differ from density.',
isReady: true,
aspectRatio: 3 / 4,
componentsUsed: ['Chat', 'ChatMessageList', 'Layout', 'Text', 'Avatar'],
diff --git a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.tsx b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.tsx
index d70a690b66..0bece04e96 100644
--- a/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.tsx
+++ b/packages/cli/templates/blocks/components/ChatMessageList/ChatMessageListDensity.tsx
@@ -53,8 +53,8 @@ export default function ChatMessageListDensity() {
}>
<XDSChatMessageBubble>
Density provides default spacing at every level — message
- gap, bubble padding, and gap between child elements. Use
- messageGap to tune row spacing independently.
+ gap, bubble padding, and gap between child elements. Use gap
+ to tune row spacing independently.
</XDSChatMessageBubble>
</XDSChatMessage>
</XDSChatMessageList>
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index 5fa0469b0f..75581821ee 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -46,7 +46,7 @@ export const docs = {
},
{name: 'scrollToTopAction', type: '() => Promise<void>', description: 'Async action fired when user scrolls to top. Use for loading older messages. Wrapped in useTransition — shows a spinner at the top while pending.'},
{name: 'density', type: "'compact' | 'balanced' | 'spacious'", description: 'Visual density — flows to child messages via context.', default: "'balanced'"},
- {name: 'messageGap', type: 'SpacingStep', description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.'},
+ {name: 'gap', type: 'SpacingStep', description: 'Gap between top-level message rows. Defaults to the selected density; override for LLM event streams or independent rows that need different spacing from density.'},
],
},
{
@@ -220,7 +220,7 @@ export const docs = {
bestPractices: [
{ guidance: true, description: 'Compose messages using MessageList > Message > Bubble for consistent sender-aware styling and density.' },
{ guidance: true, description: 'Set the density prop to control spacing globally — compact for sidebars, balanced for most views, spacious for long-form reading. Individual messages can override.' },
- { guidance: true, description: 'Use messageGap when top-level rows are independent (for example, LLM tool events or streamed blocks) and list spacing needs to be tuned separately from density.' },
+ { guidance: true, description: 'Use gap when top-level rows are independent (for example, LLM tool events or streamed blocks) and list spacing needs to be tuned separately from density.' },
{ guidance: true, description: 'Use the group prop on bubbles (first, middle, last) when a single sender sends multiple consecutive messages — it tightens corner radius to visually connect them.' },
{ guidance: true, description: 'Use XDSChatSystemMessage with variant="divider" for date separators and default for inline status notices like joins, leaves, or topic changes.' },
{ guidance: true, description: 'Put name on the first bubble and metadata on the last bubble in a message so they align with the bubble\'s inline padding.' },
@@ -312,7 +312,7 @@ export const docsZh = {
emptyState: '列表无消息时显示的内容。',
scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',
density: '视觉密度,通过上下文传递给子消息。',
- messageGap: '顶层消息行之间的间距。默认跟随密度;当 LLM 事件流等独立行需要不同间距时可覆盖。',
+ gap: '顶层消息行之间的间距。默认跟随密度;当 LLM 事件流等独立行需要不同间距时可覆盖。',
},
},
{
@@ -462,7 +462,7 @@ export const docsDense = {
bestPractices: [
{ guidance: true, description: 'MessageList > Message > Bubble for sender-aware styling.' },
{ guidance: true, description: 'Density prop controls global spacing — compact for sidebars, balanced default, spacious for reading.' },
- { guidance: true, description: 'messageGap tunes top-level row spacing separately from density for independent LLM/tool-event rows.' },
+ { guidance: true, description: 'gap tunes top-level row spacing separately from density for independent LLM/tool-event rows.' },
{ guidance: true, description: 'Group prop on bubbles (first/middle/last) for consecutive same-sender messages — tightens corner radius.' },
{ guidance: true, description: 'SystemMessage: divider variant for date breaks, default for status notices.' },
{ guidance: true, description: 'Name on first bubble, metadata on last — aligns with bubble inline padding.' },
@@ -485,7 +485,7 @@ export const docsDense = {
emptyState: 'content when no msgs',
scrollToTopAction: 'async action at scroll top; load older msgs',
density: 'visual density; flows to children via context',
- messageGap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
+ gap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',
},
},
{
diff --git a/packages/core/src/Chat/XDSChatMessageList.test.tsx b/packages/core/src/Chat/XDSChatMessageList.test.tsx
index 0936e2edf0..5f4b0f89f7 100644
--- a/packages/core/src/Chat/XDSChatMessageList.test.tsx
+++ b/packages/core/src/Chat/XDSChatMessageList.test.tsx
@@ -47,9 +47,9 @@ describe('XDSChatMessageList', () => {
expect(el.className).toContain('compact');
});
- it('accepts messageGap independently from density', () => {
+ it('accepts gap independently from density', () => {
render(
- <XDSChatMessageList density="compact" messageGap={6} data-testid="list">
+ <XDSChatMessageList density="compact" gap={6} data-testid="list">
<div>msg</div>
</XDSChatMessageList>,
);
diff --git a/packages/core/src/Chat/XDSChatMessageList.tsx b/packages/core/src/Chat/XDSChatMessageList.tsx
index f1eedf350e..9a8c89f269 100644
--- a/packages/core/src/Chat/XDSChatMessageList.tsx
+++ b/packages/core/src/Chat/XDSChatMessageList.tsx
@@ -9,7 +9,7 @@
* @position Presentational message container — holds XDSChatMessage children
*
* Renders a container with role="log" for chat message histories.
- * Handles density context, configurable message gap, empty state,
+ * Handles density context, configurable gap, empty state,
* a spacer that pushes messages to the bottom, and an infinite scroll sentinel.
*
* Auto-scroll and the scroll-to-bottom button are owned by
@@ -66,11 +66,11 @@ export interface XDSChatMessageListProps extends XDSBaseProps<HTMLDivElement> {
/**
* Gap between top-level message rows, using the spacing scale.
- * Defaults to the selected density's message gap. Override this when each
+ * Defaults to the selected density's gap. Override this when each
* row is independent (for example, LLM event streams where messages cannot
* be grouped) and row spacing should be tuned separately from density.
*/
- messageGap?: SpacingStep;
+ gap?: SpacingStep;
}
// =============================================================================
@@ -123,7 +123,7 @@ const styles = stylex.create({
},
});
-const messageGapStyles = stylex.create({
+const gapStyles = stylex.create({
0: {
gap: spacingVars['--spacing-0'],
},
@@ -167,7 +167,7 @@ const messageGapStyles = stylex.create({
* Presentational container for chat messages.
*
* Renders messages in a flex column with density-based spacing.
- * Override messageGap to tune row spacing separately from density.
+ * Override gap to tune row spacing separately from density.
* A spacer pushes content to the bottom when the list isn't full.
* Supports loading older messages via `scrollToTopAction`.
*
@@ -188,7 +188,7 @@ export function XDSChatMessageList({
emptyState,
scrollToTopAction,
density = 'balanced',
- messageGap,
+ gap,
xstyle,
className,
style,
@@ -237,14 +237,13 @@ export function XDSChatMessageList({
const contextValue = useMemo(() => ({density}), [density]);
- const gapStyle =
+ const densityGapStyle =
density === 'compact'
? styles.gapCompact
: density === 'spacious'
? styles.gapSpacious
: styles.gapBalanced;
- const messageGapStyle =
- messageGap == null ? null : messageGapStyles[messageGap];
+ const gapOverrideStyle = gap == null ? null : gapStyles[gap];
return (
<XDSChatListContext value={contextValue}>
@@ -262,7 +261,7 @@ export function XDSChatMessageList({
)}>
<div
ref={innerRef}
- {...stylex.props(styles.inner, gapStyle, messageGapStyle)}>
+ {...stylex.props(styles.inner, densityGapStyle, gapOverrideStyle)}>
{/* Sentinel for infinite scroll */}
{scrollToTopAction && <div ref={sentinelRef} aria-hidden />}