Stack

여러 항목을 서로 겹쳐 놓아 한 줄이 아니라 하나의 더미로 읽히게 합니다. 한 작업에 붙은 얼굴들, 한 벌의 카드, 책상 위의 서류처럼 항목 하나하나보다 전체 개수가 중요한 자리를 위한 것입니다.

import { Avatar, Stack } from 'neba';

<Stack ring>
  <Avatar name="Jane Doe" />
  <Avatar name="Kim Minji" />
</Stack>;

Props

Prop	타입	기본값	설명
direction	'horizontal' | 'vertical' | 'diagonal'	'horizontal'	더미가 자라는 방향. diagonal은 가로로 흐르면서 한 칸씩 내려앉습니다
overlap	number | string	—	각 항목이 앞선 항목 아래로 들어가는 거리. 숫자는 px이고, 지정하지 않으면 size의 일정 비율입니다
drop	number | string	—	흐르지 않는 축으로 각 항목이 내려앉는 거리. diagonal만 읽으며 기본값은 overlap입니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	쌓는 것들의 크기. overlap의 기본값을 정하는 데에만 쓰입니다
max	number	—	나머지가 overflow로 넘어가기 전까지 그려지는 개수. 지정하지 않으면 전부 그립니다
total	number	—	전체 개수. 앞의 몇 개만 전달받았을 때를 위한 것으로, 없으면 children 개수로 계산합니다
overflow	(hidden: number) => ReactNode	—	들어가지 못한 개수를 받아 더미 맨 뒤에 놓일 항목을 만듭니다
front	'first' | 'last'	'first'	어느 쪽 끝이 더미의 맨 앞인지
scaleStep	number	1	앞 항목 대비 곱해지는 배율. 0.94면 한 단계마다 6%씩 작아집니다
opacityStep	number	1	투명도에 대한 같은 값. 등장 애니메이션의 페이드와 곱해집니다
ring	boolean	false	각 항목 둘레에 페이지 표면색 실선을 그립니다. 비슷한 톤의 형태 둘이 겹치면 그 사이에 경계가 전혀 없기 때문입니다
transition공통	NebaTransition	—	각 항목이 도착하는 방식. 라이브러리 공통 transition 어휘입니다
stagger공통	number	0	항목마다 더해지는 지연(ms). 더미가 나타나는 대신 한 장씩 놓이게 만드는 값입니다
durationStep공통	number	0	항목마다 재생 시간에 더해지는 값(ms). 0 아래로는 내려가지 않습니다
reverse공통	boolean	false	마지막 항목부터 실행합니다. 순서만 뒤집힙니다
children	ReactNode	—	쌓을 것들. 최상위 자식 하나가 항목 하나입니다

모든 네이티브 <div> 속성이 그대로 전달됩니다. 자체 표면을 그리지 않으므로 variant, color, elevation은 없습니다. 그것은 쌓이는 대상의 몫입니다.

겹침은 translate가 아니라 margin이라, 상자 크기가 내용과 정확히 일치하고 Stack 뒤에 오는 내용도 올바른 너비를 기준으로 배치됩니다. size는 overlap의 기본값을 정할 때에만 읽습니다.

각 항목은 자기 래퍼 안에 그려지고 자식은 손대지 않은 채 통과합니다. 그래서 무엇이든 쌓을 수 있습니다. 아바타를 감싼 Tooltip이든, 다른 컴포넌트의 .map()이 만들어 낸 것이든. 자식에 직접 쓰는 것은 ring 하나뿐인데, 실선은 그것이 두르는 모양을 따라가야 하기 때문입니다.

공통 축은 prop 규약을 보세요.

예시

direction

기본값 horizontal은 inline 축을 따라 더미를 쌓고, vertical은 아래로 내려갑니다. diagonal은 horizontal처럼 옆으로 흐르면서 drop만큼 한 칸씩 내려앉습니다. 부채처럼 펼쳐진 카드 더미입니다.

import { Card, Stack, Typography } from 'neba';

function Sheet({ label }: { label: string }) {
  return (
    <Card size="sm" className="w-32">
      <Typography level="caption">{label}</Typography>
    </Card>
  );
}

const SHEETS = ['Invoice', 'Receipt', 'Contract'];

export default function StackDirection() {
  return (
    <div className="flex w-full flex-wrap items-start gap-10">
      {(['horizontal', 'vertical', 'diagonal'] as const).map((direction) => (
        <div key={direction} className="flex flex-col gap-2">
          <Typography level="caption" color="secondary">
            {direction}
          </Typography>
          <Stack direction={direction} overlap={28} drop={14}>
            {SHEETS.map((sheet) => (
              <Sheet key={sheet} label={sheet} />
            ))}
          </Stack>
        </div>
      ))}
    </div>
  );
}

overlap과 drop

overlap은 더미가 흐르는 축에서 각 항목이 앞선 항목 아래로 들어가는 거리입니다. CSS 길이나 픽셀 숫자를 받습니다. 지정하지 않으면 size의 일정 비율입니다. drop은 나머지 한 축이고, 두 축으로 움직이는 것은 diagonal뿐이라 그것만 읽습니다. 기본값은 overlap입니다.

scaleStep, opacityStep, front

scaleStep은 앞 항목 대비 배율을 곱합니다. 0.94면 한 단계마다 6%씩 작아져 더미가 뒤로 물러납니다. opacityStep은 투명도에 같은 일을 합니다. front는 어느 쪽 끝이 맨 앞인지 정합니다. 기본값 first라서 더미를 앞쪽 가장자리부터 읽으면 앞에서 뒤 순서로 읽힙니다.

import { Card, Stack, Typography } from 'neba';

const CARDS = ['Today', 'Tomorrow', 'Thursday', 'Friday'];

export default function StackDepth() {
  return (
    <div className="flex w-full flex-wrap items-start gap-10">
      <div className="flex flex-col gap-2">
        <Typography level="caption" color="secondary">
          scaleStep=0.94 · opacityStep=0.75
        </Typography>
        <Stack direction="diagonal" overlap={64} drop={10} scaleStep={0.94} opacityStep={0.75}>
          {CARDS.map((day) => (
            <Card key={day} size="sm" className="w-36" title={day} elevation={1} />
          ))}
        </Stack>
      </div>

      <div className="flex flex-col gap-2">
        <Typography level="caption" color="secondary">
          front=&quot;last&quot;
        </Typography>
        <Stack
          direction="diagonal"
          overlap={64}
          drop={10}
          scaleStep={0.94}
          opacityStep={0.75}
          front="last"
        >
          {CARDS.map((day) => (
            <Card key={day} size="sm" className="w-36" title={day} elevation={1} />
          ))}
        </Stack>
      </div>
    </div>
  );
}

max, total, overflow

max는 나머지가 더미 맨 뒤의 항목 하나로 합쳐지기 전까지 그려지는 개수입니다. total은 전체 개수로, 앞의 몇 개만 넘겨받은 더미를 위한 것입니다. overflow는 들어가지 못한 개수를 받아 그 자리를 대신할 것을 돌려줍니다.

<Stack max={3} total={12} overflow={(hidden) => <Avatar initials={`+${hidden}`} />}>

transition과 stagger

transition은 라이브러리 공통 등장 애니메이션 어휘이고, 각 항목에 적용됩니다. stagger는 항목마다 지연을 그만큼(ms) 더해 더미가 한꺼번에 나타나는 대신 한 장씩 놓이게 만듭니다. durationStep은 재생 시간에 같은 일을 하고, reverse는 마지막 항목부터 실행합니다.

import { useState } from 'react';
import { Avatar, Button, Card, Stack, Typography } from 'neba';

const TEAM = ['Anya Sol', 'Theo Quinn', 'Lucas Adebayo', 'Nadia Rowan', 'Noa Marin'].map(
  (name) => ({ name, src: `/samples/people/${name.toLowerCase().replace(' ', '-')}.jpg` })
);
const CARDS = ['Alpha', 'Beta', 'Gamma', 'Delta'];

export default function StackDealt() {
  const [run, setRun] = useState(0);

  return (
    <div className="flex w-full flex-col gap-4">
      <Button variant="outline" size="sm" onClick={() => setRun((n) => n + 1)}>
        Deal again
      </Button>

      <div key={run} className="flex flex-wrap items-start gap-10">
        <div className="flex flex-col gap-2">
          <Typography level="caption" color="secondary">
            transition=&quot;fade&quot; · stagger=90
          </Typography>
          <Stack ring transition="fade" stagger={90}>
            {TEAM.map((person) => (
              <Avatar key={person.name} name={person.name} src={person.src} />
            ))}
          </Stack>
        </div>

        <div className="flex flex-col gap-2">
          <Typography level="caption" color="secondary">
            transition=&quot;zoom&quot; · stagger=120 · reverse
          </Typography>
          <Stack
            direction="diagonal"
            overlap={56}
            drop={12}
            scaleStep={0.96}
            transition="zoom"
            stagger={120}
            reverse
          >
            {CARDS.map((name) => (
              <Card key={name} size="sm" className="w-32" title={name} elevation={1} />
            ))}
          </Stack>
        </div>
      </div>
    </div>
  );
}

접근성

• Stack은 <div>이고 아무것도 알리지 않습니다. 더미가 한 무리를 뜻한다면(작업에 붙은 사람들, 폴더 안의 파일들) role과 이름을 주거나 개수를 옆에 글로 적으세요.
• overflow 표시도 평범한 항목으로 그려지므로 거기서 렌더링한 것이 그대로 읽힙니다. +38 하나로는 전달되는 것이 거의 없으니 나머지는 aria-label로 적어 주세요.