Docs

docs/system/components/message-attachment.md

Message File Attachment

packages/ui/src/message-attachment.tsx

메시지에 붙은 파일 하나를 말풍선 바깥의 카드로 표시한다. 파일 icon, 이름, 형식과 크기 한 줄, 내려받는 action 을 소유한다.

역할과 경계

  • MessageFileAttachment 는 파일 하나의 표시다. 여러 파일은 카드를 여럿 세워 대화 화면이 쌓는다.
  • 파일을 열거나 받아 오지 않는다. 누르면 무엇이 일어나는지는 download 로 받는다.
  • 말풍선 안에 넣지 않고 말풍선 바깥에 같은 방향으로 둔다. 그 배치 규칙은 message-bubble.md의 「파일은 말풍선 바깥에 두기」가 소유한다. 시각과 메시지의 전달 상태도 말풍선이 갖고 이 카드는 갖지 않는다.
  • 카드가 보이는 값은 모두 이 파일 하나의 것이다. 그래서 Property 이름에 file 을 앞에 붙이지 않고 name·format·size 로 받는다. 시각적인 크기 단계가 없으므로 size 가 다른 것을 뜻할 자리도 없다.
  • 크기와 형식의 표기는 화면이 정해서 넘긴다. 컴포넌트는 바이트 수를 받아 「2.4 MB」로 바꾸지 않는다. 「2.4 MB」와 「2,516 KB」 가운데 무엇으로 보일지는 화면의 결정이다.
  • 화면에 보이는 문구와 접근 가능한 이름은 모두 Property 로 받는다. 컴포넌트는 언어를 갖지 않으므로 어느 locale 에서나 같은 코드로 쓴다.
  • 모서리는 interaction.md의 「공통 Control Radius」를 따르지 않는다. 컨트롤과 나란히 놓이는 요소가 아니므로 자기 값 14px 을 쓴다.

Anatomy

  1. Container: 카드 하나의 면이다. 폭과 경계를 소유한다
  2. File icon: 중립 면 위의 파일 icon 이다. 받지 않으면 문서 icon 이다
  3. Name: 파일 이름 한 줄이다. 넘치면 말줄임한다
  4. Meta (Optional): 형식과 크기를 가운데 점으로 이은 한 줄이다
  5. Download action (Optional): 오른쪽의 내려받는 자리다. download 를 넘길 때만 그린다
Message File Attachment
├─ File icon
├─ Name
├─ Meta (Optional)
└─ Download action (Optional)

Properties

  • name: 필수 문자열이다. Name 에 그대로 표시하며 카드 폭을 넘으면 말줄임한다
  • format: 「PDF」처럼 파일 형식을 가리키는 짧은 표기다. Meta 의 앞자리다
  • size: 「2.4 MB」처럼 이미 꼴을 갖춘 파일 크기다. Meta 의 뒷자리다
  • icon: File icon 자리에 서는 요소다. 넘기지 않으면 문서 icon 을 쓴다
  • download: { label, href?, onDownload? }. Download action 이다. 넘기지 않으면 그 자리를 그리지 않는다
    • label: 필수다. Download action 의 접근 가능한 이름이다. 「계약서.pdf 다운로드」처럼 파일 이름을 담은 문장으로 넘긴다
    • href: 주소로 바로 받을 수 있는 파일의 주소다. 넘기면 Download action 이 <a download> 가 된다
    • onDownload: 눌렀을 때다. href 와 함께 넘기면 anchor 의 click 에서도 불린다

색

  • Container: 배경 oe-background-primary, 경계 oe-border-secondary, 글자 oe-foreground-primary
  • File icon 자리: 배경 oe-background-secondary, icon oe-foreground-secondary
  • Name: oe-foreground-primary
  • Meta: oe-foreground-tertiary
  • Download action: icon 은 oe-foreground-tertiary 이고 hover 에서 oe-foreground-primary 로 올라간다. hover 면은 공용 hover 겹이다
  • Focus ring: 2px oe-focus-ring

카드는 상태를 뜻하지 않으므로 어느 자리에도 brand·status 색을 쓰지 않는다.

폭과 경계

  • 카드 폭은 224px 로 고정이고 담는 폭이 그보다 좁으면 그 폭까지 줄어든다. 좌우 어느 방향에 놓여도 같은 폭으로 서서 연속된 파일 카드의 변이 어긋나지 않는다.
  • 경계는 1px 선이지만 폭을 차지하지 않는 겹으로 그린다. 카드가 224px 바깥으로 1px 씩 자라 말풍선과 변이 어긋나는 것을 막는다.
  • 긴 파일 이름은 Name 한 줄만 말줄임한다. 카드를 늘리지 않고 Meta 와 Download action 의 자리도 움직이지 않는다.
  • Meta 는 format 과 size 가운데 넘어온 것만 그린다. 둘 다 넘기면 가운데 점으로 잇고, 하나만 넘기면 점 없이 그 하나만 선다. 둘 다 없으면 Meta 줄 자체가 없다. 카드 높이는 그래도 달라지지 않는다 — 높이를 정하는 것은 글자가 아니라 36px icon 자리이고, Name 한 줄만 그 가운데에 선다.

Download action

  • download 를 넘기지 않으면 자리를 그리지 않는다. 받을 수 없는 파일에 눌리지 않는 button 을 남기지 않는다.
  • href 를 넘기면 <a download> 로, onDownload 만 넘기면 <button type="button"> 으로 그린다. 둘의 겉모습은 같다.
  • 주소로 바로 받을 수 있는 파일에는 href 를 쓴다. anchor 여야 가운데 클릭과 「다른 이름으로 저장」이 살아 있다. download 속성은 같은 출처의 주소에만 걸린다.
  • 토큰을 붙여 받아 와야 하는 파일, 받기 전에 확인을 받아야 하는 파일에는 onDownload 를 쓴다.
  • Download action 은 icon 하나이고 글자를 두지 않는다. 뜻은 download.label 이 aria-label 로 담당한다.

Behavior

  • File icon 자리는 aria-hidden 이다. 뜻은 Name 과 Meta 글자가 담당하므로 받은 icon 이든 기본 icon 이든 화면 낭독기가 읽지 않는다.
  • File icon 은 받은 것이든 기본 것이든 16px 로 선다. 크기를 icon 이 아니라 자리가 걸어 36px 자리의 가운데가 흔들리지 않는다.
  • Download action 은 focus-visible 에서 2px oe-focus-ring 을 갖는다.
  • 뿌리는 data-slot="message-attachment" 를 갖고, 조각은 message-attachment-icon·message-attachment-name·message-attachment-meta·message-attachment-download 다.
  • className 은 Container 에 붙는다. 폭과 여백, 경계를 지우지 않고 덧붙으며 같은 축의 값만 덮는다.

Guidelines

말풍선 바깥에 같은 방향으로 두기

  • 파일은 말풍선의 Content 에 넣지 않고 말풍선 아래 같은 방향에 둔다. Incoming 에서는 Avatar 자리만큼 들여 Content 의 시작점에 맞춘다.
  • 시각은 카드 아래 한 줄에 대화 화면이 둔다. 카드는 시각을 갖지 않는다.

형식과 크기를 나눠 넘기기

  • 가운데 점은 컴포넌트가 이어 붙인다. 화면마다 구분 기호를 다시 적지 않는다.
  • 파일 이름에 확장자가 있어도 format 을 함께 넘긴다. 이름이 말줄임되면 확장자가 먼저 사라지므로 형식은 Meta 가 지킨다.
  • 크기를 모르는 파일은 size 를 넘기지 않는다. 「알 수 없음」 같은 문구를 넣지 않는다.

받을 수 있을 때만 Download action 을 두기

  • 지워진 파일, 권한이 없는 파일에는 download 를 넘기지 않는다. 눌러도 되지 않는 button 을 보이지 않는다.
  • download.label 에 파일 이름을 담는다. 카드가 여럿 쌓인 대화에서 「다운로드」만으로는 어느 파일인지 갈리지 않는다.

형식마다 icon 을 바꿀 때 바깥에서 고르기

  • 형식에 따라 icon 을 가르는 표는 컴포넌트가 갖지 않는다. 쓰는 화면이 icon 으로 넘긴다.
  • 그림 파일에도 이 카드를 쓴다. 썸네일로 보이는 길은 아직 없다.

Specification

자리 값
Container 폭 224px, 담는 폭이 좁으면 그 폭까지
Container 모서리 14px
Container 경계 1px, 폭을 차지하지 않는 겹
Container 안쪽 여백 10px
조각 사이 간격 8px
File icon 자리 36px 정사각, 모서리 10px
File icon 16px
Name 12px Medium, line-height 16px
Meta 11px, line-height 16.5px
Download action 32px(icon 16px + 여백 8px), 모서리 10px
카드 높이 56px. icon 자리 36px 과 위아래 여백 10px 이 정하므로 Meta 가 없어도 같다

현재 정의하지 않은 항목

  • 여러 파일을 한 카드에 담는 길을 두지 않았다. 파일 하나가 카드 하나이며 묶음을 알리는 표시가 없다.
  • 올리는 중의 진행률을 두지 않았다. 카드는 다 올라간 파일만 보인다.
  • 미리보기 썸네일을 두지 않았다. 그림 파일도 icon 과 이름으로 보인다.
  • 형식에 따른 icon 표를 두지 않았다. 형식의 목록은 제품이 정하므로 icon 으로 받는다.
  • 파일을 눌러 여는 길을 두지 않았다. 카드 전체는 누르는 자리가 아니고 Download action 하나만 누른다.
  • 지우는 action 을 두지 않았다. 보낸 파일을 거두는 것은 메시지를 삭제하는 것이며 그 규칙은 message-bubble.md가 소유한다.
  • 받을 수 없는 파일의 표시를 두지 않았다. 지워진 파일이나 권한이 없는 파일을 알리는 상태가 없다.