Message Bubble
packages/ui/src/message-bubble.tsx
대화 화면에서 메시지 하나를 발신·수신 방향에 맞춘 말풍선으로 표시한다. 작성자, 시간, 전달 상태, 읽지 않은 수와 메시지 action 을 함께 소유한다.
역할과 경계
MessageBubble은 메시지 하나의 표시다. 대화 전체의 순서, 날짜 구분선, 읽지 않은 메시지의 경계(unread boundary)와 읽음 처리 action 은 conversation-level 동작이므로 대화 화면이 그린다. 컴포넌트는 그 결과를unreadMessageCount와unreadRecipientCount로 받아 Bubble 옆에 숫자로만 표시한다.TypingIndicator는 같은 파일이 내보내는 별도 컴포넌트다. 기존 메시지의 상태가 아니라 상대방이 새 메시지를 작성 중인 thread 상태이므로MessageBubble의 Property 로 두지 않는다.- 파일은
MessageBubble의 Content 에 넣지 않고 말풍선 바깥의 독립된MessageFileAttachment로 표시한다. 메시지 입력은MessageComposer가 담당한다. 둘은 아직초안이며 이 문서는 그 규칙을 소유하지 않는다. - 화면에 보이는 문구와 접근 가능한 이름은 모두 Property 로 받는다. 컴포넌트는 언어를 갖지 않으므로 어느 locale 에서나 같은 코드로 쓴다.
- 모서리는 interaction.md의 「공통 Control Radius」를 따르지 않는다. 컨트롤과 나란히 놓이는 요소가 아니므로 자기 값 16px 을 쓴다.
- 전달 상태에서
sent와delivered를 구분하지 않고sent하나만 쓴다. 상대가 읽었는지는unreadRecipientCount가 말한다.
Anatomy
- Avatar (Optional): 작성자 initials 를 담은 32px 원이다. Incoming 에서만 그린다
- Author: Bubble 위의 작성자 이름이다. Incoming 에서만 그린다
- Bubble: Content 를 담는 채움 면이다
- Content: 메시지 본문(
children)이다 - Sidecar (Optional): Bubble 옆 바깥 아래의 자리다. 읽지 않은 수, 모두 읽음 icon, 전송 실패 표시와 Action bar 가 이 한 자리를 나눠 쓴다
- Metadata row: Bubble 아래의 한 줄이다. Outgoing 의 Sender label (Optional), 시간, 전달 상태와 전송 실패 action 이 놓인다
- Action bar (Optional): hover 또는 keyboard focus 에서 Sidecar 자리에 나타나는 복사·삭제 button 이다
Message Bubble
├─ Avatar (Optional)
├─ Author
├─ Bubble
│ └─ Content
├─ Sidecar (Optional)
│ ├─ Unread count · Read icon · Failed mark
│ └─ Action bar (Optional)
└─ Metadata row
├─ Sender label (Optional)
├─ Time
├─ Delivery state
└─ Failed actions (Optional)
Incoming 은 왼쪽에서 Avatar → Author → Bubble 순으로 시작하고 Sidecar 를 Bubble 오른쪽에 둔다. Outgoing 은 오른쪽에서 Bubble 만으로 시작하고 Sidecar 를 Bubble 왼쪽에 둔다.
Properties
direction:incoming | outgoing. 필수다. Incoming 은 상대가 보낸 메시지, Outgoing 은 현재 사용자가 보낸 메시지다author,initials,time: 필수 문자열이다.author는 Incoming 의 Author 에,initials는 Avatar 에 쓰고,time은 Metadata row 에 그대로 표시한다. 시각의 형식은 화면이 정해서 넘긴다children: Content 다deliveryState:sending | sent | read | failed. 넘기지 않으면 전달 상태를 그리지 않는다. Outgoing 에 쓴다deliveryCopy:Record<MessageDeliveryState, string>. 네 상태의 표시 문구이자 접근 가능한 이름이다.deliveryState를 넘겨도 이것이 없으면 전달 상태를 그리지 않는다unreadRecipientCount:number. Outgoing 에서 아직 읽지 않은 참여자 수다. 1 이상이면 Sidecar 에 숫자로,0이면read와 함께 모두 읽음 icon 으로 표시한다. 넘기면(0포함) Metadata row 에는 전달 상태(icon 과failed문구)를 그리지 않는다unreadRecipientLabel: 그 숫자의 접근 가능한 이름이다. 「아직 읽지 않은 참여자 3명」처럼 수를 담은 문장으로 넘긴다unreadMessageCount:number. Incoming 에서 현재 사용자가 아직 읽지 않은 새 메시지 수다. 1 이상이면 Sidecar 에 숫자로 표시하며 최신 Incoming 하나에만 넘긴다unreadMessageLabel: 그 숫자의 접근 가능한 이름이다deleted:false | true, 기본값false. 삭제된 메시지다deletedLabel: 삭제 안내 문구다.deleted와 함께 넘긴다showDeletedContent:false | true, 기본값은 방향에 따른다. Outgoing 은true로 원문을 보존하고 Incoming 은false로 원문을 숨긴다showAvatar:false | true, 기본값true. Incoming 에서만 뜻을 가진다grouped:false | true, 기본값false. 같은 발신자의 연속 메시지 가운데 첫 메시지가 아닌 것이다. Avatar 와 Author 를 생략하고 Content 만 정렬한다showTime:false | true, 기본값은grouped의 반대다. Metadata row 전체의 표시 여부다. 연속 메시지의 첫 메시지는false로 감추고, 마지막 메시지는grouped여도true로 켠다outgoingSenderLabel: Outgoing 의 Sender label 이다. 다중 관리자 화면에서 「소속팀 이름」 꼴로 넘기며 컴포넌트가 뒤에·와 시간을 이어 붙인다outgoingSenderDescription: Sender label 앞의 Info trigger 가 여는 설명이다. 넘길 때만 trigger 를 그리며 trigger 의 접근 가능한 이름으로도 쓴다actions:{ copyLabel, deleteLabel, onCopy?, onDelete? }. hover·focus 에 나타나는 Action bar 다. Incoming 은 복사만, Outgoing 은 복사와 삭제를 그린다failedActions:{ retryLabel, deleteLabel, onRetry?, onDelete? }.failed인 Outgoing 의 Metadata row 가 보일 때 hover 없이 항상 보이는 재전송·삭제 button 이다
TypingIndicator
initials: Avatar 의 initials 다label:role="status"의 접근 가능한 이름이다. 「○○님이 작성 중입니다」처럼 문장으로 넘긴다showAvatar: 기본값trueclassName: Bubble 열을 감싸는 바깥 요소에 붙는다. 색·모양 규칙은 바꾸지 않는 자리다
색
- Incoming Bubble: 배경
oe-background-secondary, 글자oe-foreground-primary - Outgoing Bubble: 배경
oe-background-bold-primary, 글자oe-foreground-inverse - Avatar: 배경
oe-background-secondary, initialsoe-foreground-secondary - Author:
oe-foreground-primary - Metadata row:
oe-foreground-tertiary. Sender label 만oe-foreground-secondary다 - Sidecar 의 숫자와 모두 읽음 icon:
oe-foreground-tertiary - 전송 실패: Metadata row 의 문구는
oe-danger-foreground-primary, Sidecar 의!는oe-danger-foreground-primary원 위의oe-foreground-inverse - Action bar: 배경
oe-background-primary, 경계oe-border-secondary. icon 은oe-foreground-tertiary이고 hover 에서oe-foreground-primary로 올라간다. 삭제 icon 의 hover 는oe-danger-background-primary위의oe-danger-foreground-primary다 - Deleted Incoming: 배경
oe-background-secondary, 글자oe-foreground-secondary - Deleted Outgoing: 배경
oe-background-bold-primary, 원문oe-foreground-inverse-secondary, 안내 문구oe-foreground-inverse - Typing indicator: 배경
oe-background-secondary, 점oe-foreground-tertiary - Focus ring: 2px
oe-focus-ring
Bubble 의 배경·글자·경계는 Tailwind class 가 아니라 packages/ui/src/styles.css 의 .oe-message-bubble-incoming 과 .oe-message-bubble-outgoing 이 칠한다. 두 class 는 --oe-message-incoming-background·--oe-message-incoming-foreground·--oe-message-incoming-border 와 같은 꼴의 --oe-message-outgoing-* 변수를 먼저 읽고, 없으면 위 token 을 쓴다. 채팅방마다 다른 브랜드 색을 쓰는 화면은 이 변수만 덮어쓴다. 경계의 기본값은 투명이다.
방향과 grouping
- Incoming 은 왼쪽에서 Avatar → Author → Bubble 순으로 시작하고, Outgoing 은 오른쪽에서 Bubble 만으로 시작한다. Metadata row 도 각 방향의 시작 변에 맞춘다.
- Outgoing 은 방향만으로 현재 사용자의 메시지임을 알 수 있으므로 Author 와 Avatar 를 그리지 않는다.
author와initials는 받지만 화면에 쓰지 않으며, 「나」 나 사용자 이름을 반복 표시하지 않는다. - Author 는 Bubble 위에 두고, 시간과 전달 상태는 Bubble 채움에 넣지 않고 아래 Metadata row 에 둔다.
- 같은 발신자의 연속 메시지가 분 단위까지 같은 시각이면 첫 메시지에만 Author·Avatar 를, 마지막 메시지에만 Metadata row 를 둔다. 첫 메시지는
showTime={false}, 중간은grouped, 마지막은grouped showTime으로 넘긴다.groupedIncoming 은 Avatar 자리만큼 44px 들여 Content 의 왼쪽 시작점을 맞춘다. - Bubble 과 Sidecar 를 담는 열은 담는 폭의 82% 를 넘지 않으며
sm이상에서는 72% 다. Bubble 은 그 안에서 Sidecar 를 뺀 폭이다. - 루트 요소는
data-direction을 갖는다. 대화 화면은 메시지 목록에oe-conversation-stackclass 를 붙여 마지막이 아닌 Outgoing 아래에 20px 을 더 띄운다. Sender label 이 있는 Metadata row 가 다음 메시지와 붙지 않게 하려는 것이다. - Metadata row 는 Sender label 과 Info trigger 의 유무와 관계없이 같은 최소 높이 20px 을 유지해 1:1 과 다중 관리자 화면을 오갈 때 메시지 간격이 움직이지 않는다. Info trigger 의 click 영역에 자체 여백이 있으므로 trigger 와 Sender label 사이에는 gap 을 두지 않는다.
전달 상태와 읽지 않은 수
sending은 시계,sent는 체크 하나,read는 체크 두 개 icon 이다.failed는 icon 없이deliveryCopy.failed문구를 danger 색으로 남긴다. 어느 상태든 접근 가능한 이름은deliveryCopy의 문구다.unreadRecipientCount를 넘기지 않은 Outgoing 은 전달 상태를 Metadata row 의 시간 옆 12px icon 으로 그린다. 1:1 대화가 여기에 해당한다.- 그룹 대화의 Outgoing 은
unreadRecipientCount를 항상 넘긴다(모두 읽었으면0). 그러면 전달 상태 표시는 Sidecar 가 담당하고 Metadata row 에는 전달 상태(icon 과failed문구)를 두지 않는다. 아직 읽지 않은 참여자가 있으면 Sidecar 에 그 수를 숫자로 표시하고,read이고0이면 같은 자리에 체크 두 개 icon 을 표시한다. 모두 읽으면 숫자는 사라진다. - 전송 실패는 Sidecar 자리에
oe-danger-foreground-primary원 위의!를 표시한다.unreadRecipientCount를 넘기지 않은 Outgoing 은 Metadata row 의deliveryCopy.failed문구도 함께 남긴다. - Outgoing 의 Sidecar 는 Bubble 의 바깥 왼쪽 아래, Incoming 의 Sidecar 는 바깥 오른쪽 아래다. Outgoing 의 숫자는 읽지 않은 상대의 수, Incoming 의 숫자는 현재 사용자의 미확인 메시지 수로 뜻이 다르다.
unreadMessageCount는 unread boundary 뒤의 최신 Incoming 하나에만 넘긴다. 이전에 읽은 메시지에는 넘기지 않는다.
메시지 action
- Action bar 는 기본 상태에서 시각적으로 숨기고(
opacity: 0, pointer 무시) 루트의 hover 또는 내부 keyboard focus(focus-within)에서 나타난다. - Action bar 는 그림자 없이 Bubble 바깥의 Sidecar 자리에 놓이고 Bubble 하단선에 맞춘다. Content 영역과 배경색을 침범하지 않는다. 읽지 않은 수 숫자와 같은 자리에 겹쳐 나타나며 그동안 숫자를 가린다.
- Incoming 은 상대가 보낸 콘텐츠이므로 복사만 제공하고 삭제를 제공하지 않는다.
actions.deleteLabel과onDelete를 넘겨도 Incoming 에는 그리지 않는다. - Outgoing 은 복사와 삭제를 제공한다.
- 전송 실패는 사용자가 해결해야 하는 오류이므로 재전송·삭제 action 을 hover 에 숨기지 않는다. 두 action 은
deliveryCopy.failed문구 바로 오른쪽에 항상 보이며 모바일에서도 같은 자리에서 발견된다. 실패한 메시지에는 hover·focus Action bar 를 그리지 않는다. - 삭제된 메시지에는 Sidecar 를 만들지 않으므로 어떤 action 도 노출하지 않는다.
- 각 action button 은 Tooltip 으로 이름을 보이고 같은 문구를
aria-label로 갖는다. Tooltip 은 button 아래 가운데에 열리며 viewport 에 부딪히면 flip·shift 한다.
삭제 상태
deleted는 Bubble 안 첫 줄에 Info icon 과deletedLabel을 두고, 원문의 표시는showDeletedContent가 정한다.- Incoming 은 기본값으로 원문을 숨기고 안내 문구만 남긴다.
- Outgoing 은 발신 방향을 알 수 있도록 Outgoing 배경을 유지하고 원문을
oe-foreground-inverse-secondary로 보존한다. 별도 opacity 를 얹지 않으며showDeletedContent={false}로 원문을 숨길 수 있다. - 점선 경계를 쓰지 않고 추가 action 도 노출하지 않는다.
다중 관리자의 Sender label
- 1:1 대화의 Outgoing 은 발신자를 표시하지 않는다.
- 여러 관리자가 같은 사용자와 채팅하는 관리자 화면에서는 Metadata row 의 시간 왼쪽에
outgoingSenderLabel을 「소속팀 이름 · 시간」 꼴로 표시한다. outgoingSenderDescription을 함께 넘기면 Sender label 앞에 12px Info icon 의 trigger 를 두고, 누르면 그 설명을 Popover 로 보인다. Popover 는top-end에 열리며 viewport 와 clipping boundary 에 부딪히면 flip·shift 한다. 설명이 없으면 trigger 도 없다.- 이 이름은 관리자 사이의 구분을 위한 내부 정보다. 사용자 화면이나 사용자에게 전달되는 메시지 payload 에는 절대 노출하지 않는다.
Behavior
- Avatar 와 모든 icon 은
aria-hidden이다. 뜻은 문구 Property 가 담당한다. 숫자는unreadRecipientLabel·unreadMessageLabel, 전달 상태는deliveryCopy, action 은 각 label 이다. - 전달 상태 icon 은
aria-label과title을 함께 갖고sr-only문구를 담아 hover 와 screen reader 모두에서 읽힌다. - Action bar 의 button 은
focus-visible에서 2pxoe-focus-ring을 갖고, Tab 으로 들어오면 bar 가 나타난다. TypingIndicator는role="status"와label을 갖는다. 점 세 개는 160ms 간격으로 pulse 하며prefers-reduced-motion에서는 멈춘다.
Guidelines
Outgoing 에는 작성자와 avatar 를 두지 않기
- 방향만으로 현재 사용자의 메시지임이 읽히므로 Author 와 Avatar 를 두지 않는다. 컴포넌트가 이미 그리지 않으며, 화면이 바깥에 따로 그려 반복하지도 않는다.
- Incoming 은
showAvatar로 Avatar 를 끌 수 있다. 참여자가 둘뿐인 1:1 대화처럼 얼굴을 구분할 이유가 없는 자리가 여기에 해당한다.
Sender label 은 다중 관리자 화면에서만 넘기기
outgoingSenderLabel과outgoingSenderDescription은 여러 관리자가 같은 사용자를 상대하는 관리자 화면에서만 넘긴다. 1:1 대화와 사용자 화면에는 넘기지 않는다.- 이 값은 사용자에게 가는 payload 에 담지 않는다.
전달 상태는 Outgoing 에만 넘기기
deliveryState·deliveryCopy·failedActions·unreadRecipientCount는 현재 사용자가 보낸 메시지의 상태다. Incoming 에는 넘기지 않는다.- Incoming 이 갖는 숫자는
unreadMessageCount하나다.
읽음 처리는 대화 단위로 두기
- 대화의 읽음 상태와 읽음 처리 action 은 메시지마다 반복하지 않고 현재 대화의 마지막 메시지 아래에만 둔다.
- 수동 읽음 처리 action 은 hover action 이 아니며 읽지 않은 상태에서 항상 보인다. 그 안의 Info icon 은 hover 에서 답장으로도 읽음 처리된다는 것을 안내하고, tooltip 은
top-end에 두며 부딪히면 flip·shift 한다. - 수동 방식은 명시적인 읽음 처리 또는 답장 완료에 대화를 읽음으로 바꾸고, 자동 방식은 대화를 확인한 시점에 읽음으로 처리한다.
- 수동 방식의 미확인 메시지는 개별 Bubble 에 badge 를 반복하지 않고, 마지막으로 읽은 메시지와 새 메시지 사이에 unread boundary 와 개수를 둔다. boundary 뒤의 최신 Incoming 하나에만
unreadMessageCount를 넘겨 같은 개수를 Sidecar 에 보인다. - 읽음 처리 또는 답장 뒤에는 unread boundary, 읽음 처리 action 과 Sidecar 의 숫자가 함께 사라진다.
파일은 말풍선 바깥에 두기
- 파일은 Content 에 넣지 않고 Bubble 아래 같은 방향에
MessageFileAttachment로 둔다. Incoming 에서는 Avatar 자리만큼 들여 Content 의 시작점에 맞춘다.
모든 action 을 상시 펼치지 않기
- Desktop 에서는 hover·focus 의 contextual action 만 쓴다. 전송 실패의 재전송·삭제만 항상 보이는 예외다.
Specification
| 자리 | 값 |
|---|---|
| Bubble 모서리 | 16px |
| Bubble 안쪽 여백 | 좌우 14px, 위아래 8px |
| Bubble 과 Sidecar 를 담는 열의 최대 폭 | 82%, sm 이상 72% |
| Content 글자 | 14px, line-height 1.625 |
| Avatar | 32px 원, initials 11px Medium |
| Avatar 와 본문 열 사이 | 12px |
grouped Incoming 들여쓰기 |
44px |
| Author | text-oe-label 13px/16px Semibold |
| Metadata row | 12px, 최소 높이 20px, Bubble 과 4px |
| 전달 상태 icon | 12px |
| Sidecar | 최소 32×32px, Bubble 과 6px |
| Sidecar 의 모두 읽음 icon·실패 표시 | 14px |
| Action bar | 모서리 8px, 안쪽 여백 2px, 1px 경계 |
| Action button | 26px(icon 14px + 여백 6px), 모서리 6px |
| Info trigger | 20px, icon 12px |
| Sender description Popover | 최대 폭 288px, top-end, 6px 띄움 |
| Typing indicator | 높이 40px, 좌우 16px, 모서리 16px, 점 6px 셋, 간격 4px |
oe-conversation-stack 의 Outgoing 아래 간격 |
20px |
현재 정의하지 않은 항목
- Mobile 의 contextual action 방식을 정하지 않았다. Desktop 은 hover·focus 이며, 전송 실패 action 만 어느 기기에서나 항상 보인다.
- 브랜드 채팅 테마의 값을 정하지 않았다.
--oe-message-*변수 자리만 두고 기본값은 위 「색」의 token 이다. - 말줄임을 두지 않았다. 긴 메시지는 그대로 줄바꿈된다.