Transfer

두 개의 목록과 그 사이의 화살표입니다. 한쪽에는 고를 수 있는 것 전부, 다른 쪽에는 이미 고른 것. 칩으로 가득 찬 필드가 더 이상 읽히지 않을 만큼 선택지가 많을 때 씁니다.

import { Transfer } from 'neba';

<Transfer
  items={[
    { value: 'status', label: 'Status' },
    { value: 'commit', label: 'Commit' }
  ]}
  value={shown}
  onValueChange={setShown}
/>;

Props

Prop	타입	기본값	설명
variant공통	'solid' | 'outline' | 'text'	'outline'	두 패널의 표면 무게
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	높이와 타입 스케일
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 임의 색상값은 받지 않습니다
density공통	'default' | 'compact'	'default'	여백만 바꿉니다. 높이와 글자 크기는 그대로
items *	readonly TransferItem[]	—	양쪽에 놓일 수 있는 모든 것. 두 목록이 보여주는 순서 그대로입니다
value	readonly string[]	—	오른쪽에 있는 것들. onValueChange와 함께 쓰면 controlled 컴포넌트가 됩니다
defaultValue	readonly string[]	—	처음에 오른쪽에 있는 것들 (uncontrolled)
onValueChange	(value: string[]) => void	—	무언가 옮겨질 때마다 호출됩니다
sourceLabel	ReactNode	—	왼쪽 목록의 제목. 기본값은 locale의 표현입니다
targetLabel	ReactNode	—	오른쪽 목록의 제목
searchable	boolean	false	각 목록 위에 필터를 둡니다. 행을 숨길 뿐 옮기지는 않습니다
height	number | string	220	각 목록의 높이. 숫자는 px입니다
disabled	boolean	false	아무것도 체크되거나 옮겨지지 않습니다
locale	string	—	BCP 47 태그. 제목·버튼·필터를 이 언어로 씁니다. 지원하지 않는 태그는 영어로

<div>의 모든 속성이 color를 제외하고 그대로 전달됩니다.

TransferItem

Prop	타입	기본값	설명
value *	string	—	항목을 식별하는 값. value가 이것들의 목록입니다
label *	ReactNode	—	행에 쓰이는 말
disabled	boolean	false	목록에는 있지만 옮길 수 없습니다

선택지가 열 개 남짓이라면 multiple을 켠 Combobox나 Checkbox 한 열이 더 작은 컴포넌트입니다. 이 컴포넌트는 "내가 결국 무엇을 골랐는가"에 별도의 목록이 필요할 때 제 몫을 합니다.

예시

value와 onValueChange

값은 오른쪽에 있는 것이며, items가 준 순서를 따릅니다. 그래서 보냈다가 되돌려도 행의 자리가 바뀌지 않습니다. 행에 체크하는 것은 고르는 것이 아닙니다. 체크는 다음 버튼이 무엇을 옮길지를 말하고, 값은 그것들이 어느 쪽에 있는지를 말합니다.

searchable

각 목록 위에 필터를 둡니다. 행을 숨길 뿐 옮기지는 않으며, 숨겨진 행은 버튼이 옮기는 대상에 들어가지 않습니다.

import { Transfer } from 'neba';

const PEOPLE = [
  'Kim Minji',
  'Alex Park',
  'Sam Lee',
  'Noa Cohen',
  'Ravi Patel',
  'Jane Doe',
  'Hana Sato',
  'Luis Ortiz',
  'Mia Fischer'
].map((name) => ({ value: name.toLowerCase().replace(/\s+/g, '-'), label: name }));

export default function TransferSearchable() {
  return (
    <Transfer
      searchable
      size="sm"
      className="max-w-2xl"
      items={PEOPLE}
      defaultValue={['sam-lee']}
      sourceLabel="Everyone"
      targetLabel="On this channel"
    />
  );
}

height · disabled

height는 각 목록의 높이입니다. disabled인 항목은 자기 목록에 남고 체크되지도 옮겨지지도 않습니다. 컴포넌트 전체의 disabled는 모든 항목에 같은 일을 합니다.

import { Transfer } from 'neba';

const ITEMS = [
  { value: 'read', label: 'Read' },
  { value: 'write', label: 'Write' },
  { value: 'deploy', label: 'Deploy' },
  { value: 'billing', label: 'Billing', disabled: true }
];

export default function TransferStates() {
  return (
    <div className="flex w-full max-w-2xl flex-col gap-6">
      <Transfer size="sm" height={120} items={ITEMS} defaultValue={['read']} />
      <Transfer size="sm" height={120} items={ITEMS} defaultValue={['read']} disabled />
    </div>
  );
}

locale · sourceLabel · targetLabel

제목과 버튼과 필터의 문구는 locale에서 옵니다. sourceLabel과 targetLabel은 두 제목을 직접 씁니다. 대개는 이쪽을 쓰게 됩니다. "선택 가능"과 "선택함"이 그 두 목록의 실제 이름인 경우는 드뭅니다.

접근성

• 모든 행이 라벨과 연결된 진짜 checkbox이므로 Tab과 Space만으로 전부 조작할 수 있습니다.
• 각 목록 위의 체크는 그 목록의 Select all이며, 일부만 체크된 동안에는 mixed 상태를 알립니다.
• 두 버튼 모두 "Move to selected", "Move to available"이라는 이름을 가지며, 옮길 것이 없으면 사용 불가가 됩니다.