An open source design system that's fully customizable and agent ready
TypeScript
feat(chat): add ChatMessageList align prop for top-aligned lists (#2572) (#3933)
Jiun Shin6759843deb0a
diff --git a/.changeset/chatmessagelist-add-align-prop-for-top-aligned-l-xm43.md b/.changeset/chatmessagelist-add-align-prop-for-top-aligned-l-xm43.mdnew file mode 100644index 0000000000..ebae48ff36--- /dev/null+++ b/.changeset/chatmessagelist-add-align-prop-for-top-aligned-l-xm43.md@@ -0,0 +1,16 @@+---+'@astryxdesign/core': patch+---++[feat] ChatMessageList: add an `align` prop for top-aligned message lists+(#2572).++- `align?: 'top' | 'bottom'` (default `'bottom'`). `'bottom'` keeps the+ existing behavior: a flex spacer fills free space so a short conversation+ sits just above the composer. `'top'` omits the spacer so messages start at+ the top and grow downward — better for log-style or document-style lists.+- Only changes the resting position of a non-full list. Once messages overflow+ the container the spacer collapses to zero in both modes, so ChatLayout+ auto-scroll-to-bottom behavior is unchanged.++@jiunshinndiff --git a/apps/storybook/stories/Chat.stories.tsx b/apps/storybook/stories/Chat.stories.tsxindex 8db0d19b8e..b0b608ee50 100644--- a/apps/storybook/stories/Chat.stories.tsx+++ b/apps/storybook/stories/Chat.stories.tsx@@ -591,3 +591,61 @@ export const MultiBubble: StoryObj = {</div>),};+export const Alignment: StoryObj = {+ name: 'Alignment',+ render: () => {+ const shortConversation = (align: 'top' | 'bottom') => (+ <div+ style={{+ flex: 1,+ minWidth: 0,+ display: 'flex',+ flexDirection: 'column',+ border: '1px solid var(--color-border-primary)',+ borderRadius: 8,+ overflow: 'hidden',+ }}>+ <div+ style={{+ padding: '8px 12px',+ borderBottom: '1px solid var(--color-border-primary)',+ fontSize: 12,+ fontWeight: 600,+ textTransform: 'uppercase',+ letterSpacing: '0.05em',+ }}>+ align="{align}"+ </div>+ <div+ style={{+ flex: 1,+ display: 'flex',+ flexDirection: 'column',+ minHeight: 0,+ }}>+ <ChatMessageList align={align}>+ <ChatMessage sender="user">+ <ChatMessageBubble>Just one short message.</ChatMessageBubble>+ </ChatMessage>+ <ChatMessage+ sender="assistant"+ avatar={<Avatar name="Navi" size="small" />}>+ <ChatMessageBubble>+ {align === 'top'+ ? 'Top alignment keeps messages at the top — good for logs and document-style lists.'+ : 'Bottom alignment keeps a short thread just above the composer — the familiar messaging layout.'}+ </ChatMessageBubble>+ </ChatMessage>+ </ChatMessageList>+ </div>+ </div>+ );++ return (+ <div style={{display: 'flex', gap: 16, height: 420}}>+ {shortConversation('bottom')}+ {shortConversation('top')}+ </div>+ );+ },+};diff --git a/packages/core/src/Chat/ChatMessageList.doc.mjs b/packages/core/src/Chat/ChatMessageList.doc.mjsindex 276eb95705..13f516dc9a 100644--- a/packages/core/src/Chat/ChatMessageList.doc.mjs+++ b/packages/core/src/Chat/ChatMessageList.doc.mjs@@ -7,7 +7,7 @@ export const docs = {subComponentOf: 'Chat',displayName: 'Chat Message List',isHiddenFromOverview: true,- description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full.`,+ description: `Presentational message container with density context and infinite scroll support. Provides role="log" with aria-live="polite" for accessibility. A flex spacer pushes messages to the bottom when the list isn't full; set align="top" to start messages at the top instead.`,props: [{name: 'children',@@ -45,6 +45,12 @@ export const docs = {type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10',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: 'align',+ type: "'top' | 'bottom'",+ description: "Vertical alignment when the list is shorter than its container. 'bottom' fills free space with a spacer so short conversations sit above the composer; 'top' omits the spacer so messages start at the top. Only affects a non-full list; overflowing lists scroll identically, preserving auto-scroll-to-bottom.",+ default: "'bottom'",+ },{name: 'isStreaming',type: 'boolean',@@ -65,6 +71,7 @@ export const docsZh = {scrollToTopAction: '用户滚动到顶部时触发的异步操作。用于加载更早的消息。',density: '视觉密度,通过上下文传递给子消息。',gap: '顶层消息行之间的间距。默认跟随密度;当 LLM 事件流等独立行需要不同间距时可覆盖。',+ align: "列表内容不足一屏时的垂直对齐方式。'bottom' 用占位块填满剩余空间,让简短对话贴近输入框;'top' 省略占位块,让消息从顶部开始。仅影响未填满的列表,溢出后两种模式滚动一致,保持自动滚动到底部。",isStreaming: '是否有助手消息正在流式输出。标记日志为 aria-busy,让屏幕阅读器等待并在完成后一次性播报,而不是每个 token 都重复播报。',},};@@ -80,6 +87,7 @@ export const docsDense = {scrollToTopAction: 'async action at scroll top; load older msgs',density: 'visual density; flows to children via context',gap: 'top-level row gap; defaults to density spacing; override for independent LLM/tool rows',+ align: "'top'|'bottom' (def bottom); bottom spacer pushes short lists down, top starts at top; overflow scrolls same either way",isStreaming: 'assistant streaming? marks log aria-busy so SR announces the completed msg once',},};diff --git a/packages/core/src/Chat/ChatMessageList.test.tsx b/packages/core/src/Chat/ChatMessageList.test.tsxindex 385303ea6c..1322757d2e 100644--- a/packages/core/src/Chat/ChatMessageList.test.tsx+++ b/packages/core/src/Chat/ChatMessageList.test.tsx@@ -83,4 +83,50 @@ describe('ChatMessageList', () => {);expect(screen.getByTestId('chat-list')).toBeTruthy();});++ // With no scrollToTopAction the spacer is the only aria-hidden element in+ // the list, so its presence maps 1:1 to the aria-hidden count.+ it('renders the bottom spacer by default', () => {+ render(+ <ChatMessageList data-testid="list">+ <div>msg</div>+ </ChatMessageList>,+ );+ expect(+ screen.getByTestId('list').querySelectorAll('[aria-hidden]'),+ ).toHaveLength(1);+ });++ it('renders the bottom spacer when align="bottom"', () => {+ render(+ <ChatMessageList align="bottom" data-testid="list">+ <div>msg</div>+ </ChatMessageList>,+ );+ expect(+ screen.getByTestId('list').querySelectorAll('[aria-hidden]'),+ ).toHaveLength(1);+ });++ it('omits the spacer when align="top"', () => {+ render(+ <ChatMessageList align="top" data-testid="list">+ <div>msg</div>+ </ChatMessageList>,+ );+ expect(+ screen.getByTestId('list').querySelectorAll('[aria-hidden]'),+ ).toHaveLength(0);+ });++ it('still renders children when align="top"', () => {+ render(+ <ChatMessageList align="top">+ <ChatMessage sender="assistant">+ <ChatMessageBubble>Hello</ChatMessageBubble>+ </ChatMessage>+ </ChatMessageList>,+ );+ expect(screen.getByText('Hello')).toBeTruthy();+ });});diff --git a/packages/core/src/Chat/ChatMessageList.tsx b/packages/core/src/Chat/ChatMessageList.tsxindex 6eca3d8f31..3f2468f4ce 100644--- a/packages/core/src/Chat/ChatMessageList.tsx+++ b/packages/core/src/Chat/ChatMessageList.tsx@@ -10,7 +10,8 @@** Renders a container with role="log" for chat message histories.* Handles density context, configurable gap, empty state,- * a spacer that pushes messages to the bottom, and an infinite scroll sentinel.+ * a configurable spacer (align) that pushes messages to the bottom,+ * and an infinite scroll sentinel.** Auto-scroll and the scroll-to-bottom button are owned by* ChatLayout. When used standalone (without a layout), the list@@ -73,6 +74,24 @@ export interface ChatMessageListProps extends BaseProps<HTMLDivElement> {*/gap?: SpacingStep;+ /**+ * Vertical alignment of messages when the list is shorter than its+ * container.+ *+ * - `'bottom'` (default): a spacer fills the free space and pushes+ * messages to the bottom, so a short conversation sits just above the+ * composer — the familiar messaging-app layout.+ * - `'top'`: the spacer is omitted, so messages start at the top and grow+ * downward — better for document-style or log-style lists.+ *+ * This only changes the resting position of a non-full list. Once messages+ * overflow the container the spacer collapses to zero in both modes, so+ * ChatLayout auto-scroll-to-bottom behavior is identical either way.+ *+ * @default 'bottom'+ */+ align?: 'top' | 'bottom';+/*** Whether an assistant message is actively streaming into the list.*@@ -183,7 +202,8 @@ const gapStyles = stylex.create({** Renders messages in a flex column with density-based spacing.* Override gap to tune row spacing separately from density.- * A spacer pushes content to the bottom when the list isn't full.+ * By default a spacer pushes content to the bottom when the list isn't full;+ * set `align='top'` to start messages at the top instead.* Supports loading older messages via `scrollToTopAction`.** Auto-scroll and the scroll-to-bottom button are owned by@@ -204,6 +224,7 @@ export function ChatMessageList({scrollToTopAction,density = 'balanced',gap,+ align = 'bottom',isStreaming = false,xstyle,className,@@ -291,8 +312,11 @@ export function ChatMessageList({</div>)}- {/* Spacer pushes messages to bottom when list isn't full */}- <div {...stylex.props(styles.spacer)} aria-hidden />+ {/* Spacer pushes messages to bottom when the list isn't full.+ Omitted for top alignment so messages start at the top. */}+ {align === 'bottom' && (+ <div {...stylex.props(styles.spacer)} aria-hidden />+ )}{/* Messages or empty state */}{hasChildren ? (