DataList

키와 값 쌍의 목록입니다. 주문 요약, 프로필, 설정 창, 도구 호출의 입력에 씁니다. 네이티브 dl이라서 용어와 상세 내용은 각각 dt와 dd입니다. 간격은 밀도를 따르고, 용어와 상세 내용의 색, 용어의 굵기, 용어 열의 너비는 datalist contract 토큰에서 가져옵니다.

<DataList.Root aria-label="Order summary">
  <DataList.Item>
    <DataList.Term>Order</DataList.Term>
    <DataList.Details>#10482</DataList.Details>
  </DataList.Item>
  <DataList.Item>
    <DataList.Term>Status</DataList.Term>
    <DataList.Details>Shipped on 2027-01-04</DataList.Details>
  </DataList.Item>
  <DataList.Item>
    <DataList.Term>Total</DataList.Term>
    <DataList.Details>$42.00</DataList.Details>
  </DataList.Item>
</DataList.Root>

Server Components는 @tounsoo/todae/data-list에서 가져올 수 있습니다. 이 엔트리에는 'use client'도 훅도 없습니다. 메인 @tounsoo/todae 엔트리는 클라이언트 모듈입니다.

DataList.Item은 용어 하나와 그 상세 내용을 담는 div입니다. dl 안에서 이런 div는 유효하며, 스타일을 주거나 옮기거나 key를 줄 수 있는 한 행입니다. 항목마다 DataList.Term 하나와 DataList.Details 하나를 주세요. 용어 하나에 값이 여럿이면 그 DataList.Details 하나 안에, 예를 들어 목록으로 넣으세요.

방향

orientation="vertical"은 용어를 상세 내용 위에 둡니다. 기본값인 "horizontal"은 용어를 상세 내용 옆의 열에 둡니다. 이 값은 CSS에서 data-orientation으로 보입니다.

<DataList.Root orientation="vertical" aria-label="Profile">
  <DataList.Item>
    <DataList.Term>Name</DataList.Term>
    <DataList.Details>Mina Park</DataList.Details>
  </DataList.Item>
  <DataList.Item>
    <DataList.Term>Email</DataList.Term>
    <DataList.Details>mina@example.com</DataList.Details>
  </DataList.Item>
</DataList.Root>

열

minItemSize는 항목을 여러 열로 배치하며, 각 열은 "10rem"처럼 준 CSS 길이보다 좁아지지 않습니다. 너비가 허락하는 만큼 열이 들어가므로 미디어 쿼리 없이 다시 배치되고, minItemSize보다 좁은 목록에서는 하나뿐인 열이 그 너비에 맞게 줄어듭니다. 항목은 DOM 순서대로 행을 채우므로 읽는 순서는 소스 순서 그대로입니다. 열 사이의 간격은 datalist.gap.between-columns이고, 행 사이의 간격은 그대로 datalist.gap.row입니다. Grid는 div를 렌더링하고 항목은 dl의 자식이어야 하므로, Grid로는 목록의 항목을 배치할 수 없습니다.

<DataList.Root orientation="vertical" minItemSize="10rem" aria-label="Plan">
  <DataList.Item>
    <DataList.Term>Plan</DataList.Term>
    <DataList.Details>Team</DataList.Details>
  </DataList.Item>
  <DataList.Item>
    <DataList.Term>Seats</DataList.Term>
    <DataList.Details>12 of 20</DataList.Details>
  </DataList.Item>
  {/* … */}
</DataList.Root>

각 항목은 자기 열 안에서 방향을 유지합니다. 가로 항목은 열이 용어 열, datalist.gap.column, 상세 내용의 최소 너비를 더한 것보다 좁으면 쌓이므로, 가로 항목을 여러 열로 놓으려면 minItemSize를 calc(var(--todae-datalist-term-width) + var(--todae-datalist-gap-column) + var(--todae-datalist-details-min-width)) 이상으로 주세요.

내용에 맞춰 목록의 크기를 정하는 부모 안에서는 열의 개수가 항목 텍스트의 너비에 따라 달라집니다. 목록에 너비를 주는 방법은 다음 절에 있습니다.

좁은 너비

가로 목록은 용어 열과 읽기 좋은 너비의 상세 내용 열이 들어갈 만큼 넓지 않으면 스스로 쌓입니다. 용어는 최대 datalist.term.width까지 차지하며, 그보다 좁은 목록에서는 줄어듭니다. 상세 내용이 datalist.details.min-width보다 좁아지게 되면 용어 아래로 내려갑니다. 컨테이너 쿼리를 쓰지 않으므로 회사는 두 토큰을 모두 바꿀 수 있습니다. 쌓인 용어와 상세 내용 사이의 간격은 datalist.gap.stacked입니다.

목록은 부모가 주는 너비를 차지합니다. 플렉스 행이나 inline-block처럼 내용에 맞춰 목록의 크기를 정하는 부모는 텍스트 너비만큼만 주므로 행이 쌓입니다. 그런 곳에서는 목록에 너비를 주세요. 예를 들어 플렉스 행에서는 flex: 1을 줍니다.

접근성을 지키는 조합

Todae가 맡는 것: dl, dt, dd 요소. 각 dt는 용어로, 각 dd는 그 정의나 상세 내용으로 노출되며, 보조 기술은 이를 설명 목록으로 알릴 수 있습니다. ARIA는 추가하지 않으며, 각 쌍을 감싸는 div는 접근성 트리에 나타나지 않습니다.

직접 제공할 것: 이름이 필요한 목록에는 aria-label이나 aria-labelledby로 준 이름. 그 자체로 의미가 통하는 용어 텍스트. 예를 들어 "Total"이나 "Ship to"입니다.

주의할 점: 용어가 아닌 내용, 예를 들어 버튼이나 폼 컨트롤을 DataList.Term 안에 넣는 것. dt는 그 세부 내용의 용어로 노출됩니다. 행마다 열이 여러 개인 데이터를 DataList에 담는 것. 그것은 표이며, 표는 각 셀에 열 머리글을 연결해 줍니다.

언제 쓰나

쓸 때: 주문, 사람, 요금제, 도구 호출의 입력처럼 하나의 대상에 대한 이름 있는 값들.

쓰지 않을 때: 여러 대상의 같은 필드가 행으로 이어질 때 → Table. 사용자가 편집하는 값 → Field.

Props